Troubleshooting

This page covers common issues encountered when operating BadgerPanel and their solutions. Always start by checking the relevant logs.

---

Viewing Panel Logs

cd ~/badgerpanel

# View logs for all services
docker compose logs --tail 100

# View logs for a specific service
docker compose logs api --tail 100
docker compose logs web --tail 100
docker compose logs nginx --tail 100
docker compose logs mysql --tail 100
docker compose logs redis --tail 100

# Follow logs in real-time
docker compose logs -f api

---

Installation Issues

Installer Fails with Docker Error

Symptom: The installer exits with "Docker is not installed."

Solution: Install Docker before running the installer:

curl -fsSL https://get.docker.com | bash

Verify the installation:

docker --version
docker compose version

Services Fail to Start

Symptom: docker compose ps shows services as exited or restarting.

# Check which services are failing
docker compose ps

# View the failing service's logs
docker compose logs api
docker compose logs mysql

Common causes:

• Port 80 or 443 already in use by another web server (Apache, nginx, etc.)
• Insufficient disk space for Docker images
• Docker daemon not running: systemctl start docker

Port Conflicts

Symptom: Nginx fails to start with "bind: address already in use."

# Find what's using port 80 or 443
ss -tlnp | grep -E ':80|:443'

Stop the conflicting service (e.g., systemctl stop apache2) or reconfigure the panel to use different ports.

---

Connection Issues

Cannot Access the Panel in Browser

Checklist:

1. Verify services are running: docker compose ps
2. Check nginx logs: docker compose logs nginx
3. Verify your domain's DNS A record points to the panel server's IP: dig panel.example.com
4. Ensure ports 80 and 443 are open: sudo ufw status or check your cloud provider's security group
5. Test local connectivity: curl -v https://localhost from the panel server

Node Shows as Offline

Checklist:

1. Check the daemon is running on the node: systemctl status badger-daemon
2. Verify panel.url in the daemon config is correct and reachable from the node: curl -I https://panel.example.com
3. Check daemon logs: journalctl -u badger-daemon --tail 50
4. Ensure the node's API key hasn't been regenerated in the panel
5. Check firewall rules between the node and the panel (the daemon connects outbound on port 443)

WebSocket Connection Drops

Symptom: Console output stops updating or the node disconnects frequently.

Causes:

• A reverse proxy or load balancer is not configured for WebSocket upgrades
• Network timeout settings are too aggressive
• The daemon's heartbeat is not reaching the panel within the timeout window

Check that your nginx configuration includes WebSocket upgrade headers for the API paths.

---

Server Issues

Server Won't Start

1. Check the server's console log in the panel for error messages
2. Verify the node has enough available resources (memory and disk)
3. Check daemon logs for container errors: journalctl -u badger-daemon --tail 50
4. Ensure the Docker image specified in the egg can be pulled on the node: docker pull <image>

Server Stuck in "Installing"

Symptom: A server remains in installing status indefinitely.

1. Check the install output in the server's console tab
2. Check daemon logs for errors during the install script execution
3. If the install script hangs, kill the server from the admin panel and try reinstalling

Server Crashes Repeatedly

If a server crashes more than 3 times within 10 minutes (default crash detection window), the daemon stops restarting it and marks it as crashed. Check the console output for the error causing the crash. Common causes include:

• Insufficient memory allocation
• Corrupted game files (try reinstalling)
• Port already in use by another process

---

Database Issues

Game Server Database Connection Errors

1. Verify the database host is accessible from the node's IP address
2. Check credentials in the database host configuration under Admin > Database Hosts
3. Ensure the database host's firewall allows connections from game server nodes on port 3306

Panel Database Errors

Check the API logs for database-related errors:

docker compose logs api | grep -i "database\|mysql\|sql"

Common causes:

• MySQL service crashed: docker compose restart mysql
• Connection pool exhausted under heavy load

---

SSL Certificate Issues

1. Verify your domain's DNS A record is pointing to the correct server IP
2. Check nginx logs: docker compose logs nginx
3. Ensure ports 80 and 443 are not blocked (Let's Encrypt requires port 80 for HTTP challenges)
4. Manually renew: sudo certbot renew
5. Check certificate expiry: sudo certbot certificates

---

Getting Help

If you cannot resolve an issue using this guide:

1. Check the daemon and API logs for specific error messages
2. Join the BadgerPanel Discord for community support
3. Open a support ticket through the BadgerPanel website