Troubleshooting and Maintenance
When Nginx breaks, you need to move fast. This module is organized by symptom — find your error, get the fix.
First Response Checklist
# 1. Test config syntax (run this BEFORE every reload)
sudo nginx -t
# 2. Check error log
sudo tail -50 /var/log/nginx/error.log
# 3. Check service status
sudo systemctl status nginx
# 4. Test HTTP response
curl -I http://localhost
curl -sv https://example.com/ 2>&1 | head -30
# 5. Check listening ports
sudo ss -tlnp | grep nginx
# 6. Check disk space
df -h /var/log/
What You Will Learn
- How to read Nginx error log messages and understand what they mean
- How to fix 502, 504, 403, 404, and SSL errors
- How to debug PHP-FPM connection issues
- How to validate SSL certificates from the CLI
- How to upgrade Nginx safely
- How to back up and restore Nginx configuration
Topics in This Module
- Reading Error Logs — Log levels, upstream errors, permission messages
- 502 Bad Gateway — PHP-FPM down, upstream unreachable, socket issues
- 504 Gateway Timeout — Upstream slow, timeout values, PHP execution time
- 403 Forbidden — File permissions,
autoindex,try_filesmisconfig - 404 Not Found —
rootvsalias,try_files, missing index files - SSL Errors — Cert mismatch, Cloudflare 525/526, expired cert, chain issues
- Config Validation —
nginx -t,nginx -T, debugging include order - Upgrades and Maintenance — Safe upgrade steps, config backup, rollback
Best Practices
- Always run
nginx -tbeforenginx -s reload— a bad config will crash Nginx on full restart - Set
error_log /var/log/nginx/error.log warn;in production — debug level creates enormous logs - Back up
/etc/nginx/before any major change:sudo tar -czf /root/nginx-backup-$(date +%Y%m%d).tar.gz /etc/nginx/ - Pin Nginx version in production:
sudo apt-mark hold nginx
Success Checkpoint
By the end of this module you should be able to diagnose any common Nginx error from the log, apply the correct fix, and validate your change before reloading.