Troubleshooting

This guide covers common issues users encounter with Hydrodactyl and their solutions.

Installation Issues

Docker Container Won't Start

Problem: Docker container exits immediately or fails to start.

Solutions:

1. Check container logs:

   docker logs hydrodactyl-panel
   docker logs hydrodactyl-wings

2. Verify port conflicts:

   netstat -tulpn | grep :8080
   netstat -tulpn | grep :443

3. Check docker-compose.yml configuration:

   • Ensure volume paths exist
   • Verify environment variables are correctly set
   • Check network configuration

Database Connection Failed

Problem: Panel cannot connect to the database.

Solutions:

1. Verify database is running:

   docker ps | grep database

2. Check database credentials in .env:

   DB_CONNECTION=mysql
   DB_HOST=database
   DB_PORT=3306
   DB_DATABASE=hydrodactyl
   DB_USERNAME=hydrodactyl
   DB_PASSWORD=your-password

3. Test database connection:

   docker exec -it hydrodactyl-panel php artisan tinker
   >>> DB::connection()->getPdo()

Permission Errors

Problem: File permission errors during installation.

Solutions:

1. Set correct ownership:

   sudo chown -R www-data:www-data /var/www/hydrodactyl
   sudo chmod -R 755 /var/www/hydrodactyl/storage
   sudo chmod -R 755 /var/www/hydrodactyl/bootstrap/cache

2. Check SELinux status:

   sudo setenforce 0

Panel Issues

502 Bad Gateway

Problem: Panel returns 502 error.

Solutions:

1. Check PHP-FPM status:

   docker exec -it hydrodactyl-panel supervisorctl status php-fpm

2. Restart services:

   docker-compose restart panel

3. Check nginx configuration:

   docker exec -it hydrodactyl-panel nginx -t

Login Loop

Problem: Users get stuck in login loop after authentication.

Solutions:

1. Clear session cache:

   docker exec -it hydrodactyl-panel php artisan cache:clear
   docker exec -it hydrodactyl-panel php artisan config:clear

2. Check session configuration:

   SESSION_DRIVER=database
   SESSION_SECURE_COOKIES=true

3. Verify SSL certificate is valid.

Server Not Showing in Panel

Problem: Created servers don't appear in the panel.

Solutions:

1. Check Wings connection:

   docker exec -it hydrodactyl-wings wings debug

2. Verify daemon configuration:

   • Check API token matches
   • Ensure communication URL is accessible
   • Verify SSL certificate

3. Restart Wings daemon:

   docker-compose restart wings

Server Issues

Server Won't Start

Problem: Server creation succeeds but server won't start.

Solutions:

1. Check server logs in the panel

2. Verify server configuration:

   • Memory allocation
   • CPU allocation
   • Disk space
   • Port allocation

3. Check Docker container status:

   docker exec -it hydrodactyl-wings docker ps -a

4. Inspect server container logs:

   docker logs [container-id]

Installation Stuck

Problem: Server installation process gets stuck.

Solutions:

1. Check available disk space on the node
2. Verify download URLs in egg configuration
3. Check network connectivity
4. Restart installation:

   # From panel
   Settings → Server → Reinstall Server

Console Not Working

Problem: Server console doesn't update or respond to commands.

Solutions:

1. Check WebSocket connection:

   • Open browser developer tools
   • Check Network tab for WebSocket errors

2. Verify Wings daemon is running

3. Check firewall settings:

   sudo ufw status
   sudo ufw allow 8080

Backup Issues

Backup Failed

Problem: Server backups fail to complete.

Solutions:

1. Check backup configuration:

   BACKUP_DRIVER=s3  # or local

2. Verify storage credentials

3. Check available disk space

4. Review backup logs:

   docker exec -it hydrodactyl-wings tail -f /var/log/pterodactyl/backup.log

Large Backup Times

Problem: Backups take extremely long to complete.

Solutions:

1. Use .pyroignore file to exclude large directories
2. Configure backup compression:

   BACKUP_COMPRESSION_LEVEL=6

3. Increase backup timeout:

   BACKUP_TIMEOUT=3600

Performance Issues

Slow Panel Loading

Problem: Panel interface loads slowly.

Solutions:

1. Enable caching:

   CACHE_DRIVER=redis

2. Optimize database:

   docker exec -it hydrodactyl-panel php artisan optimize:clear
   docker exec -it hydrodactyl-panel php artisan optimize

3. Check resource usage:

   docker stats hydrodactyl-panel

High Memory Usage

Problem: Panel or Wings using excessive memory.

Solutions:

1. Monitor resource usage:

   docker stats --no-stream

2. Adjust PHP memory limit:

   PHP_MEMORY_LIMIT=256M

3. Limit server allocations appropriately

Network Issues

Node Communication Failed

Problem: Panel cannot communicate with Wings nodes.

Solutions:

1. Test connectivity:

   curl -k https://node-domain:8080/api/system

2. Check firewall rules:

   sudo ufw allow 8080/tcp

3. Verify SSL certificates

4. Check DNS resolution

Port Allocation Issues

Problem: Unable to assign ports to servers.

Solutions:

1. Check available ports:

   # From Wings node
   netstat -tulpn | grep :25565

2. Add more allocations:

   • Admin → Nodes → Select Node → Allocations
   • Add new port ranges

3. Check port conflicts with other services

Security Issues

SSL Certificate Errors

Problem: SSL/HTTPS certificate issues.

Solutions:

1. Check certificate validity:

   openssl x509 -in /path/to/cert.pem -text -noout

2. Renew Let's Encrypt certificate:

   docker exec -it hydrodactyl-panel certbot renew

3. Use self-signed certificates for development only

Authentication Issues

Problem: Users cannot authenticate properly.

Solutions:

1. Check 2FA configuration

2. Reset user passwords:

   docker exec -it hydrodactyl-panel php artisan tinker
   >>> $user = App\Models\User::find(1);
   >>> $user->password = Hash::make('new-password');
   >>> $user->save();

3. Verify email configuration for password resets

Debug Mode

Enabling Debug Mode

Warning: Only enable debug mode in development environments.

APP_DEBUG=true
APP_LOG_LEVEL=debug

Debugging Steps

1. Check application logs:

   docker exec -it hydrodactyl-panel tail -f storage/logs/laravel.log

2. Monitor Wings logs:

   docker exec -it hydrodactyl-wings tail -f /var/log/pterodactyl/wings.log

3. Use browser developer tools:

   • Network tab for API calls
   • Console tab for JavaScript errors
   • Application tab for storage issues

Getting Help

Discord Community

Join the Hydrodactyl Discord for community support.

GitHub Issues

Report bugs and feature requests at the GitHub repository.

Information to Include

When seeking help, please include:

1. Hydrodactyl version
2. Docker version
3. Operating system
4. Error messages (full logs)
5. Steps to reproduce
6. Configuration files (remove sensitive data)

Log Locations

• Panel logs: storage/logs/laravel.log
• Wings logs: /var/log/Pterodactyl/wings.log
• Nginx logs: /var/log/nginx/error.log
• PHP logs: /var/log/php8.2-fpm.log