GunicornNGINX502 Bad GatewayPythonDjangoLinux
What this problem usually means
Gunicorn timeouts and NGINX 502 errors usually mean NGINX cannot get a healthy response from the Python application server. The issue may sit in Gunicorn workers, a systemd service, a Unix socket, application startup, database calls, memory pressure or a reverse proxy timeout.
Production caution: Restarting Gunicorn may restore service temporarily, but it can hide the real cause. If workers are hanging, memory is low, migrations are incomplete or the app cannot start cleanly, the 502 errors can return quickly.
Common symptoms
- NGINX shows 502 Bad Gateway for a Python app
- Gunicorn workers timeout or restart repeatedly
- systemd reports the Gunicorn service as failed
- The app works from the command line but not through NGINX
- Requests fail during traffic spikes or after deployment
Common causes
- Gunicorn service failed after a package or deployment change
- Wrong socket path, permissions or upstream target
- Workers are too few, too many or timing out
- Python app cannot import settings or dependencies
- Database, Redis or external API calls are hanging
- Server memory pressure causes workers to be killed
Safe first checks
These checks help identify whether the issue is at the proxy, Gunicorn, systemd, application or server-resource layer. Adjust paths, service names and users for your environment.
Check NGINX errors
tail -100 /var/log/nginx/error.log
Check Gunicorn service
systemctl status gunicorn --no-pager
journalctl -u gunicorn -n 100 --no-pager
Check sockets and permissions
ls -lah /run/ /var/run/ 2>/dev/null | grep gunicorn
Check memory and load
free -m && uptime && df -h
Typical fixes
- Correct NGINX upstream socket or TCP target
- Align socket ownership and permissions with the NGINX user
- Fix systemd unit paths, environment files and working directory
- Review Gunicorn worker count, timeout and preload behaviour
- Check deployment changes, Python dependencies and app imports
- Investigate slow database, Redis or external API calls
- Add monitoring for worker failures, memory pressure and 5xx errors
When to get help
Get help if the Python application is production-facing, the failure affects users, the deployment path is unclear, or the system mixes NGINX, Gunicorn, systemd, Docker, databases and background services. We can review logs, confirm the cause and quote a fixed-scope fix where appropriate.
Need this fixed?
Get remote support for this issue.
Fixed technical support starts from $499. Emergency incident support is $199/hr with a minimum window.
Related guides