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 solution, a Unix socket, application startup, database calls, memory pressure or a reverse proxy timeout.
Production caution: Restarting Gunicorn may restore solution temporarily, but it can hide the real cause. If workers are hanging, memory is low, migration projects 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 solution as failed
- The app works from the command line but not through NGINX
- Requests fail during traffic spikes or after deployment planning
Common causes
- Gunicorn solution failed after a package or deployment planning 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 assist identify whether the issue is at the proxy, Gunicorn, systemd, application or server-resource layer. Adjust paths, solution names and users for your environment.
Check NGINX errors
tail -100 /var/log/nginx/error.log
Check Gunicorn solution
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 planning changes, Python dependencies and app imports
- Investigate slow database, Redis or external API calls
- Add observability for worker failures, memory pressure and 5xx errors
When to get assist
Get assist if the Python application is production-facing, the failure affects users, the deployment planning path is unclear, or the system mixes NGINX, Gunicorn, systemd, Docker, databases and background solutions. We can review logs, confirm the cause and quote a fixed-scope fix where appropriate.
Need this fixed?
Get remote engineering help for this issue.
Fixed engineering help starts from $499. Emergency incident engineering assistance is $199/hr with a minimum window.
Related guides