Updating Panel Troubleshooting

Pterodactyl Panel Troubleshooting Guide 
 Introduction 
 This document outlines common issues encountered after updating Pterodactyl Panel and provides step-by-step solutions for diagnosing and fixing these problems. The guide is based on a real troubleshooting session where a Pterodactyl panel stopped loading after an update. 
 Following the instructions in these pages should work most times. https://pterodactyl.io/panel/1.0/updating.html https://pterodactyl.io/guides/php_upgrade.html Blueprint docs if needed: https://blueprint.zip/docs/?page=getting-started/Installation Replace favicons in " /var/www/pterodactyl/public/favicons " with the ones found here https://mirror.fullbuff.gg/resources/favicons/ 
 Common Issues After Pterodactyl Updates 
 1. Panel Fails to Load 
 The panel may fail to load after an update due to several possible causes: 
 
 Missing PHP extensions 
 PHP version mismatch 
 Web server configuration issues 
 Database connection problems 
 Permission issues 
 Maintenance mode not disabled 
 Cache issues 
 
 2. Web Server Conflicts 
 One specific issue we encountered was having both Apache and NGINX trying to use port 80 simultaneously. 
 Diagnostic Steps 
 1. Check Panel Logs 
 First, examine the panel logs to identify specific errors: 
 tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log
 
 Common error messages you might see: 
 
 "could not find driver" (MySQL connection issue) 
 "Class 'DOMDocument' not found" (Missing PHP XML extension) 
 Database connection errors 
 
 2. Check Web Server Status 
 Verify that your web server is running: 
 systemctl status nginx
# or
systemctl status apache2
 
 If you see errors like "bind() to 0.0.0.0:80 failed", it means something else is using port 80. 
 3. Check What's Using Port 80 
 To identify services using port 80: 
 lsof -i :80
# or
netstat -tuln | grep :80
 
 4. Check Redis Status 
 Redis is needed for caching and queues: 
 systemctl status redis
# or
systemctl status redis-server
 
 Common Solutions 
 1. Fix Missing PHP Extensions 
 Install required PHP extensions. Make sure to use your correct PHP version (in our case, 8.3): 
 apt update
apt install -y php8.3-mysql php8.3-xml php8.3-curl php8.3-gd php8.3-mbstring php8.3-zip php8.3-bcmath php8.3-intl
 
 2. Fix Web Server Conflicts 
 If both Apache and NGINX are trying to use port 80: 
 Option 1: Use NGINX (Recommended for Pterodactyl) 
 systemctl stop apache2
systemctl disable apache2
systemctl start nginx
systemctl enable nginx
 
 Option 2: Use Apache 
 systemctl stop nginx
systemctl disable nginx
systemctl start apache2
systemctl enable apache2
 
 3. Fix PHP-FPM Configuration 
 Make sure your web server is configured to use the correct PHP version: 
 
 Check your NGINX configuration: 
 
 nano /etc/nginx/sites-available/pterodactyl.conf
 
 
 Look for the PHP-FPM socket path and update it to match your installed PHP version: 
 
 location ~ \.php$ {
 fastcgi_pass unix:/run/php/php8.3-fpm.sock; # Adjust version number as needed
 # Other configuration...
}
 
 
 Restart NGINX after making changes: 
 
 nginx -t # Test the configuration
systemctl restart nginx
 
 4. Fix Permissions 
 Set proper permissions on Pterodactyl files: 
 chown -R www-data:www-data /var/www/pterodactyl/*
chmod -R 755 /var/www/pterodactyl/storage/* /var/www/pterodactyl/bootstrap/cache/
 
 5. Clear Cache 
 Clear various caches after updates: 
 cd /var/www/pterodactyl
php artisan config:clear
php artisan view:clear
php artisan cache:clear
 
 6. Exit Maintenance Mode 
 If the panel was left in maintenance mode: 
 cd /var/www/pterodactyl
php artisan up
 
 7. Restart Queue Worker 
 Always restart the queue worker after updates: 
 systemctl restart pteroq
 
 Troubleshooting Third-party Extensions 
 If you have third-party extensions like Blueprint: 
 
 After fixing the core panel, reinstall the extension 
 Reinstall any dependencies required by the extension 
 Clear cache again after reinstalling extensions 
 
 If UI indicators show extensions as not fully installed despite working functionality, this might be a UI glitch that doesn't affect operations. 
 Preventative Measures for Future Updates 
 
 Always back up before updating 
 Check PHP version compatibility before updating 
 Make sure all required PHP extensions are installed 
 Follow the official update guide completely 
 Take note of any custom configurations or extensions you have installed 
 Monitor the logs during and after the update process 
 
 Conclusion 
 Most Pterodactyl panel issues after updates can be traced to missing PHP extensions, web server configuration mismatches, or permission problems. By systematically checking logs, verifying services, and applying the appropriate fixes, you can quickly restore functionality to your panel.