Troubleshooting

Work out what is wrong, and put it right.

Start with the log every time. It usually names the problem.

Where the logs are

Panel logs

The panel services log through Docker. Run these commands in your installation directory:

cd ~/badgerpanel

# All services
docker compose logs --tail 100

# One 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 a service as it runs
docker compose logs -f api

Daemon logs

The daemon writes to a file. It does not write to the system journal.

Node type	Log file
Linux	/var/log/badger-daemon/daemon.log
Windows	C:\BadgerDaemon\logs\daemon.log

# Linux
tail -n 100 /var/log/badger-daemon/daemon.log
tail -f /var/log/badger-daemon/daemon.log

# Windows
Get-Content C:\BadgerDaemon\logs\daemon.log -Tail 100
Get-Content C:\BadgerDaemon\logs\daemon.log -Wait

WARNING

journalctl -u badger-daemon shows almost nothing. The daemon sends its output to the log file above, not to the journal. Use the file.

Housekeeping log

The nightly cleanup job writes to /var/log/badgerpanel-prune.log. Read it if disk space drops without a clear cause.

Installation errors

Services do not start

Symptom: docker compose ps shows a service as exited or restarting.

cd ~/badgerpanel
docker compose ps
docker compose logs api
docker compose logs mysql

Common causes:

• Another web server holds port 80 or port 443.
• The disk is full. The images and the database need room.
• The Docker service is not running. Start it with systemctl start docker.

Port conflict

Symptom: The panel will not start, and says bind: address already in use.

ss -tlnp | grep -E ':80|:443'

Stop the other service, for example systemctl stop apache2. You can also change HTTP_PORT and HTTPS_PORT in the .env file, then restart the panel.

The API takes a long time to answer

A fresh installation runs about 110 database migrations and imports the bundled eggs before the API answers. That normally takes 30 to 60 seconds. On a slow disk it takes several minutes. Read docker compose logs -f api to watch the progress.

Connection errors

The panel does not open in a browser

1. Make sure that the services run. Run docker compose ps.
2. Read the web server log with docker compose logs nginx.
3. Make sure that your A record holds the IP of the panel server. Run dig panel.example.com.
4. Make sure that port 80 and port 443 are open. Run sudo ufw status, or read the security group of your cloud provider.
5. Test from the server itself. Run curl -kI https://localhost.

A node shows as offline

1. Make sure that the daemon runs.
   • Linux: systemctl status badger-daemon
   • Windows: Get-Service BadgerDaemon
2. Read the daemon log. The path is in the table above.
3. Make sure that the panel.url value in the daemon configuration is correct.
   • Linux: /etc/badger-daemon/config.yaml
   • Windows: C:\BadgerDaemon\config.yaml
4. From the node, make sure that the panel answers. Run curl -I https://panel.example.com.
5. Make sure that no firewall blocks the outbound connection from the node to the panel on port 443.
6. If somebody regenerated the registration token, install the daemon again with the new command.

A node shows as pending setup

The panel created the node, but no daemon has registered yet. Open the node in the panel, copy the install command, and run it on the machine. The registration token expires after 24 hours. Generate a new one if the old one is stale.

The console stops updating

The console and the node connection both use WebSockets. Common causes:

• A reverse proxy or a load balancer in front of the panel does not pass WebSocket upgrades.
• A proxy timeout closes long-lived connections.

If you run your own proxy in front of BadgerPanel, pass the Upgrade and Connection headers for the paths under /api/. Raise the read timeout on those paths too.

A banner reports a Self-Heal error

The panel checks its own routing when it starts. A banner names the step that failed, and new addresses do not work until you fix it. Read docker compose logs api for the reason, then restart the panel.

Server errors

A server does not start

1. Read the console output of the server in the panel.
2. Make sure that the node has free memory and free disk space.
3. Read the daemon log on that node for errors.
4. On a Linux node, make sure that the node can pull the container image. Run docker pull <image>.

A server stays in "Installing"

1. Open the Console tab of the server and read the install output.
2. Read the daemon log for errors from the install script.
3. If the install script produces no new output for a long time, open the server in Admin > Servers and reinstall it.

WARNING

Reinstall deletes all data of that server. This cannot be undone.

A server crashes again and again

The daemon restarts a crashed server on its own, up to 5 times in a row. After that it leaves the server down for you to look at.

A server that stays up for 10 minutes or more clears its crash count.

Read the console output to find the cause. Common causes:

• The memory limit is too low for the game.
• The game files are damaged. Reinstall the server.
• Another process holds the port.

Database errors

A game server cannot reach its database

1. Make sure that the database host accepts connections from the IP of the node.
2. Read the credentials of the host under Admin > Databases.
3. Make sure that the firewall of the database host allows port 3306 from your nodes.

The panel reports database errors

cd ~/badgerpanel
docker compose logs api | grep -i "database\|mysql\|sql"

Common causes:

• The MySQL container stopped. Restart it with docker compose restart mysql.
• The disk is full, so MySQL cannot write.

Certificate errors

1. Make sure that your A record holds the correct IP.
2. Read the expiry date. Run sudo certbot certificates.
3. Open the admin area. A banner appears when the certificate expires soon or has expired. Click Renew now.
4. If renewal keeps failing, read SSL certificates. The panel holds port 80, and the renewal needs it free.

Get help

If this page does not solve your problem:

1. Collect the exact error from the daemon log and the API log.
2. Join the BadgerPanel Discord for community support.
3. Open a support ticket on the BadgerPanel website.