Troubleshooting

This page covers common issues encountered when deploying and operating BadgerPanel, along with their solutions.

Checking Logs

Most issues can be diagnosed by checking service logs. Always start here:

cd /opt/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

To follow logs in real-time:

docker compose logs -f api

Installation Issues

Setup Script Fails

Symptom: ./scripts/setup.sh exits with an error.

Solutions:

• Ensure the script is executable: chmod +x scripts/setup.sh
• Run as root or with sudo
• Check that Docker and Docker Compose are installed: docker compose version
• Ensure you have an active internet connection for pulling images

Docker Compose Fails to Start

Symptom: docker compose up -d fails or containers exit immediately.

# Check which services are failing
docker compose ps

# Check individual service logs
docker compose logs api

Common causes:

• Port 80 or 443 already in use (Apache, another Nginx instance)
• Insufficient disk space for Docker images
• Missing .env file -- run the setup script first
• 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/443
ss -tlnp | grep -E ':80|:443'

Solutions:

• Stop the conflicting service (e.g., systemctl stop apache2)
• Or change the Nginx ports in docker-compose.yml

Connection Issues

Cannot Access the Panel in Browser

Symptom: Browser shows "connection refused" or times out.

Checklist:

1. Verify services are running: docker compose ps
2. Check that Nginx is healthy: docker compose logs nginx
3. Verify your domain's DNS points to the server: dig panel.your-domain.com
4. Check firewall rules allow ports 80 and 443:

# UFW (Ubuntu)
sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# firewalld (RHEL/CentOS)
sudo firewall-cmd --list-all
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

5. If using a cloud provider, check the security group/network firewall rules in your provider's dashboard

SSL Certificate Errors

Symptom: Browser shows "Your connection is not private" or similar SSL error.

Self-signed certificates: This is expected behavior. Proceed through the browser warning for development environments.

Let's Encrypt certificates:

# Check Nginx logs for certificate errors
docker compose logs nginx | grep -i cert

# Verify the certificate files exist
ls -la nginx/ssl/

Common causes:

• DNS not yet propagated (wait up to 48 hours for new domains)
• Port 80 blocked (Let's Encrypt needs HTTP access for domain validation)
• Rate limited by Let's Encrypt (max 5 duplicate certificates per week)

See the SSL Certificates guide for detailed setup instructions.

WebSocket Connection Failures

Symptom: Server console shows "connecting..." but never loads. Real-time features do not work.

Solutions:

• Verify Nginx is configured to proxy WebSocket connections (check the nginx.conf for proxy_set_header Upgrade directives)
• If using Cloudflare, ensure WebSocket support is enabled in the Cloudflare dashboard
• Check that no firewall or reverse proxy is stripping WebSocket headers

Database Issues

API Fails to Start -- Database Connection

Symptom: API logs show "dial tcp: connection refused" or "Access denied for user".

# Verify MySQL is running
docker compose ps mysql

# Test the connection manually
docker compose exec mysql mysql -u badgerpanel -p"$DB_PASSWORD" badgerpanel -e "SELECT 1;"

Solutions:

• Wait a moment -- MySQL can take 30-60 seconds to initialize on first startup
• Check that DB_PASSWORD in .env matches the MySQL container's configuration
• Verify DB_HOST is set to mysql (the Docker service name)

Migration Failures

Symptom: API logs show migration errors on startup.

docker compose logs api | grep -i migration

Solutions:

• If this is a fresh install, the database may not exist yet. Check MySQL logs: docker compose logs mysql
• For stuck migrations, check the current migration state:

docker compose exec mysql mysql -u root -p"$DB_ROOT_PASSWORD" badgerpanel \
  -e "SELECT * FROM schema_migrations;"

• If a migration partially applied, you may need to manually fix the schema. Open a support ticket with the migration error details.

Database Performance

Symptom: Panel is slow, pages take several seconds to load.

Solutions:

• Check MySQL resource usage:

docker stats badgerpanel-mysql-1

• Ensure MySQL has enough memory (at least 1 GB recommended)
• Check for slow queries:

docker compose exec mysql mysql -u root -p"$DB_ROOT_PASSWORD" -e "SHOW PROCESSLIST;"

Redis Issues

Session Errors

Symptom: Users are randomly logged out or see "session expired" errors.

# Check Redis is running
docker compose ps redis

# Test Redis connectivity
docker compose exec redis redis-cli -a "$REDIS_PASSWORD" ping

Solutions:

• Verify REDIS_PASSWORD in .env matches the Redis container's configuration
• Check Redis memory usage: docker compose exec redis redis-cli -a "$REDIS_PASSWORD" info memory
• If Redis is running out of memory, increase the container's memory limit or configure a maxmemory policy

Rate Limiting Issues

Symptom: Users hit rate limits too quickly, or rate limiting does not seem to work.

Solutions:

• Check the rate limit settings in Admin > Settings > Security
• Verify Redis is connected (rate limit counters are stored in Redis)
• Check the user's role -- each role has a rate limit multiplier

Daemon Issues

Daemon Not Connecting to Panel

Symptom: Node shows as "offline" in the admin dashboard.

Checklist:

1. Check that the daemon is running on the node: systemctl status badgerdaemon
2. Check daemon logs: journalctl -u badgerdaemon --tail 50
3. Verify the node can reach the panel: curl -I https://panel.your-domain.com
4. Check that the authentication token matches (regenerate in Admin > Nodes if needed)
5. Verify there are no firewall rules blocking outbound WebSocket connections from the node

Servers Not Starting

Symptom: Server shows "installing" or "starting" indefinitely.

# On the daemon node, check Docker
docker ps -a | grep badgerpanel
docker logs <container_id>

Solutions:

• Verify Docker is running on the node: systemctl status docker
• Check disk space: df -h -- insufficient space prevents container creation
• Check that the Docker image in the egg configuration is accessible
• Review daemon logs for specific errors: journalctl -u badgerdaemon --tail 100

SFTP Connection Refused

Symptom: SFTP client cannot connect to the daemon.

Solutions:

• Default SFTP port is 2022 -- ensure you are using the correct port
• Check that port 2022 is open in the node's firewall
• Verify the user's credentials (panel email + panel password)
• Check daemon logs for SFTP errors: journalctl -u badgerdaemon | grep -i sftp

Billing Issues

Stripe Payments Failing

Symptom: Checkout fails with a payment error.

Solutions:

• Verify STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY are correct and match (both live or both test)
• Check Stripe webhook delivery in your Stripe dashboard (Developers > Webhooks)
• Verify STRIPE_WEBHOOK_SECRET matches the webhook endpoint configuration
• Check API logs for Stripe error details: docker compose logs api | grep -i stripe

PayPal Not Redirecting

Symptom: Clicking "Pay with PayPal" does nothing or shows an error.

Solutions:

• Verify PayPal credentials (PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET)
• Ensure PAYPAL_MODE is set to sandbox for testing or live for production
• Check that your PayPal app has the correct return URLs configured

Services Not Provisioning

Symptom: Payment completes but the server is not created.

Solutions:

• Check API logs for provisioning errors: docker compose logs api | grep -i provision
• Verify the product is configured with a valid node and egg
• Ensure the target node has available resources (allocations, disk space)

Performance Issues

High Memory Usage

# Check memory usage per container
docker stats --no-stream

Solutions:

• MySQL is the most memory-hungry service. Ensure at least 1 GB is available for it.
• MinIO memory usage grows with the number of objects. Consider external S3 storage for large deployments.
• Check for memory leaks in the API by monitoring over time.

Slow Page Loads

Solutions:

1. Check API response times in the browser's developer tools (Network tab)
2. Verify Redis is working (caching reduces database load)
3. Check MySQL slow query log
4. Ensure the server has sufficient CPU and RAM
5. If using Cloudflare, enable caching for static assets

Getting Help

If you cannot resolve an issue using this guide:

1. Search the documentation for relevant guides
2. Check the Discord community for similar issues and solutions
3. Open a support ticket with:
   • BadgerPanel version (shown in Admin > Settings)
   • Relevant log output (docker compose logs api --tail 200)
   • Steps to reproduce the issue
   • Your server's OS and Docker version