Troubleshooting

​

Installation Issues

​

Database Connection Failed

Illuminate\Database\QueryException
Could not find driver (SQL: select * from information_schema.tables...)

1. Install MySQL/MariaDB PHP extension:

# Ubuntu/Debian
sudo apt install php8.3-mysql

# RHEL/CentOS
sudo yum install php-mysqlnd

2. Verify database credentials in .env:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pterodactyl
DB_PASSWORD=yourpassword

3. Test database connection:

mysql -u pterodactyl -p -h 127.0.0.1 panel

4. Check MySQL is running:

sudo systemctl status mysql
sudo systemctl start mysql

​

Composer Install Fails

Your requirements could not be resolved to an installable set of packages

1. Update Composer:

composer self-update

2. Clear Composer cache:

composer clear-cache

3. Check PHP version:

php -v  # Should be 8.2 or higher

4. Install dependencies with correct flags:

composer install --no-dev --optimize-autoloader

​

Permission Denied Errors

failed to open stream: Permission denied

1. Set proper ownership:

# If using Nginx
sudo chown -R www-data:www-data /var/www/pterodactyl

# If using Apache
sudo chown -R apache:apache /var/www/pterodactyl

2. Set proper permissions:

cd /var/www/pterodactyl
sudo chmod -R 755 storage bootstrap/cache

3. Fix SELinux contexts (RHEL/CentOS):

sudo restorecon -R /var/www/pterodactyl

​

Login and Authentication Issues

​

Cannot Login - “Invalid Credentials”

1. Reset user password:

php artisan p:user:make
# Or update existing user
php artisan p:user:password <email>

2. Clear sessions:

php artisan session:clear
redis-cli FLUSHDB  # If using Redis

3. Check session driver in .env:

SESSION_DRIVER=redis  # Or database, file

​

Two-Factor Authentication Issues

1. Disable 2FA for user:

USE panel;
UPDATE users SET use_totp = 0 WHERE email = '[email protected]';

2. Use recovery tokens if available (shown during 2FA setup)
3. Check system time is synchronized:

sudo timedatectl set-ntp true
timedatectl status

​

“Too Many Login Attempts”

1. Wait the time specified in the error message
2. Clear rate limit cache:

php artisan cache:clear
redis-cli FLUSHDB

3. Check IP address if behind proxy, configure trusted proxies in .env:

TRUSTED_PROXIES=*

​

Server Management Issues

​

Servers Stuck in “Installing” State

1. Check Wings logs:

sudo journalctl -u wings -n 100

2. Verify Wings connectivity:

curl -k https://node.example.com:8080

3. Manually reset server state:

USE panel;
UPDATE servers SET status = NULL WHERE status = 'installing';

4. Restart Wings (automatically resets failed states in v1.11+):

sudo systemctl restart wings

​

Cannot Start/Stop Servers

Server must be online in order to send commands

1. Check Wings status:

sudo systemctl status wings
sudo journalctl -u wings --since "10 minutes ago"

2. Verify server installation completed successfully
3. Check Docker container:

sudo docker ps -a | grep pterodactyl

4. Review Wings configuration:

sudo wings configure --panel-url https://panel.example.com

​

File Manager Not Loading

1. Check browser console for errors (F12)
2. Verify Wings is running and accessible
3. Check CORS configuration in .env:

APP_CORS_ALLOWED_ORIGINS=*

4. Clear browser cache and cookies
5. Verify allocation is properly assigned to server

​

Performance Issues

​

Slow Page Load Times

1. Enable caching:

php artisan config:cache
php artisan route:cache
php artisan view:cache

2. Use Redis for cache and sessions:

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

3. Enable OPcache in php.ini:

opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.revalidate_freq=2

4. Check server resources:

htop
free -h
df -h

5. Optimize database:

php artisan db:optimize

​

High CPU Usage

1. Check queue workers:

ps aux | grep artisan

2. Limit queue workers in supervisor config:

numprocs=2

3. Enable query caching in database
4. Review application logs for repeated errors:

tail -f storage/logs/laravel.log

​

High Memory Usage

1. Increase PHP memory limit in php.ini:

memory_limit = 256M

2. Restart PHP-FPM:

sudo systemctl restart php8.3-fpm

3. Check for memory leaks in queue workers:

sudo supervisorctl restart all

​

API Issues

​

401 Unauthorized

1. Verify API key is correct and not expired:

curl -H "Authorization: Bearer ptla_key" \
     -H "Accept: application/json" \
     https://panel.example.com/api/application/users

2. Check API key permissions in admin panel
3. Ensure proper headers:

Authorization: Bearer {api_key}
Accept: application/json
Content-Type: application/json

​

429 Too Many Requests

1. Implement retry logic with backoff
2. Increase rate limits in .env:

APP_API_CLIENT_RATELIMIT=512
APP_API_APPLICATION_RATELIMIT=512

3. Use request batching and includes:

# Instead of multiple requests
curl /api/application/servers/1?include=databases,allocations

4. Check rate limit headers:

X-RateLimit-Limit: 256
X-RateLimit-Remaining: 0
Retry-After: 42

​

502 Bad Gateway

1. Verify Wings is running:

sudo systemctl status wings

2. Check Wings logs:

sudo journalctl -u wings -n 50

3. Test Wings connectivity:

curl -k https://node.example.com:8080/api/system

4. Verify SSL certificates are valid
5. Check firewall rules:

sudo ufw allow 8080/tcp

​

Email Issues

​

Emails Not Sending

1. Test email configuration:

php artisan p:mail:test [email protected]

2. Check mail settings in .env:

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-api-key
MAIL_ENCRYPTION=tls
[email protected]

3. Review mail logs:

tail -f storage/logs/laravel.log | grep mail

4. Check queue worker is running:

sudo supervisorctl status

5. Verify SPF/DKIM records for email domain

​

Database Issues

​

Connection Pool Exhausted

Too many connections

1. Increase max connections in MySQL:

SET GLOBAL max_connections = 200;

2. Make permanent in my.cnf:

[mysqld]
max_connections = 200

3. Check for connection leaks:

SHOW PROCESSLIST;

4. Restart MySQL:

sudo systemctl restart mysql

​

Database Lock Errors

Deadlock found when trying to get lock

1. Retry the operation (Laravel handles this automatically)
2. Check for long-running queries:

SHOW FULL PROCESSLIST;

3. Optimize tables:

OPTIMIZE TABLE servers;
OPTIMIZE TABLE allocations;

4. Restart MySQL if persistent

​

Common Error Messages

​

”This server is in a failed install state”

UPDATE servers SET status = NULL WHERE id = SERVER_ID;

​

”No valid server identifier was included”

​

”Server transfers are already enabled”

DELETE FROM server_transfers WHERE server_id = SERVER_ID;

​

“The backup limit for this server has been reached”

​

Wings-Specific Issues

​

Getting Help

​

Collect Diagnostic Information

1. Panel version:

php artisan p:info

2. Error logs:

tail -n 100 storage/logs/laravel.log

3. System information:

php -v
composer --version
mysql --version

4. Configuration (sanitize sensitive data):

cat .env | grep -v PASSWORD | grep -v KEY | grep -v SECRET

​

Community Resources

• Discord: discord.gg/pterodactyl
• Documentation: pterodactyl.io/docs
• GitHub Issues: github.com/pterodactyl/panel/issues
• Community Guides: Search Discord pins and GitHub discussions

​

Best Practices for Asking for Help

1. Search first - Your issue may already be answered
2. Provide version information - Panel and Wings versions
3. Include error messages - Full, unredacted logs
4. Describe what you tried - Show troubleshooting steps taken
5. Be patient and respectful - Community support is volunteer-based