nginx shows 502 Bad Gateway in front of a Django app on Gunicorn
502 Bad GatewayShort answer
A 502 means nginx could not get an answer from Gunicorn. Read the nginx error log first, then the Gunicorn service log. The usual causes are Gunicorn not running, nginx proxying to a different socket or port than Gunicorn binds, a worker killed for being slower than the timeout, or a socket nginx may not open.
Fix it fast
1Find out which cause you have
Two logs answer this. The nginx error log says what nginx saw on its side of the connection. The Gunicorn unit log (adjust the unit name) says what the app did. The path below is the common default; the error_log directive in your nginx config sets the real one.
sudo tail -n 30 /var/log/nginx/error.log sudo journalctl -u gunicorn -n 50 --no-pager2Match what you see, then jump to its fix
- 1
nginx logs an upstream connection failure on every request, and the Gunicorn unit shows failed or inactiveGunicorn is not running, or it crashed while startingFix - 2
Gunicorn is active, but nginx still fails to connectnginx proxies to an address Gunicorn is not bound toFix - 3
502 only on slow views (reports, imports, large uploads); the Gunicorn log shows workers being restartedA slow request got its Gunicorn worker killedFix - 4
(13: Permission denied) while connecting to upstreamnginx may not open the Gunicorn socketFix
- 1
What does the error look like?
502 Bad Gateway(13: Permission denied) while connecting to upstream
Cause 1 of 4
Gunicorn is not running, or it crashed while starting
1Check
Ask systemd for the unit state, then read the last log lines for the Python traceback that stopped it. An import error in settings or a missing environment variable is the usual reason.
systemctl status gunicorn --no-pager
sudo journalctl -u gunicorn -n 80 --no-pager2Fix
Fix the error the traceback names, then restart the unit.
sudo systemctl restart gunicorn3Verify
Request the socket directly as the user nginx runs as. Any HTTP response, even a 400, means Gunicorn is answering.
sudo -u www-data curl --unix-socket /run/gunicorn.sock http://localhost/Confirmed by gunicorn.org
Cause 2 of 4
nginx proxies to an address Gunicorn is not bound to
1Check
Compare the address in proxy_pass with the bind address of the Gunicorn command or unit file. Gunicorn binds 127.0.0.1:8000 when you give it nothing else, so a proxy_pass that names a socket file will find no listener.
grep -R "proxy_pass" /etc/nginx/sites-enabled/
systemctl cat gunicorn | grep -i -E "bind|ExecStart"2Fix
Make both sides name the same address. For a Unix socket, nginx uses the unix: prefix and Gunicorn uses the unix: bind form.
# nginx site config
location / {
proxy_pass http://unix:/run/gunicorn.sock;
}
# Gunicorn
gunicorn --bind unix:/run/gunicorn.sock myproject.wsgi:application3Verify
Test the nginx config, reload it and request the site.
sudo nginx -t && sudo systemctl reload nginx
curl -I https://example.comConfirmed by gunicorn.org
Cause 3 of 4
A slow request got its Gunicorn worker killed
1Check
Gunicorn kills and restarts a worker that stays silent for longer than its timeout, 30 seconds by default. A request that runs longer than that loses its worker, and nginx gets no response.
sudo journalctl -u gunicorn --since '1 hour ago' --no-pager | grep -i -E 'timeout|killed|booting'2Fix
Move the slow work out of the request (a background job is the real fix). While you do that, raise the timeout for that service.
gunicorn --timeout 120 --bind unix:/run/gunicorn.sock myproject.wsgi:application3Verify
Repeat the slow request and confirm no worker restart shows in the log.
sudo journalctl -u gunicorn -fConfirmed by gunicorn.org
Cause 4 of 4
nginx may not open the Gunicorn socket
1Check
The socket owner, group and mode decide who may connect. List the socket and test it as the nginx user.
ls -l /run/gunicorn.sock
sudo -u www-data curl --unix-socket /run/gunicorn.sock http://localhost/2Fix
Give the socket to a group nginx belongs to. The full steps are on the page for that error.
# gunicorn.socket
[Socket]
ListenStream=/run/gunicorn.sock
SocketUser=www-data
SocketGroup=www-data
SocketMode=06603Verify
Restart the socket unit and run the curl test above again.
sudo systemctl daemon-reload && sudo systemctl restart gunicorn.socketConfirmed by gunicorn.org
How do I stop it coming back?
- Run Gunicorn under systemd with a socket unit, so the address and permissions live in one file.
- Give nginx and Gunicorn the same address, written once in your deploy notes.
- Keep slow work out of web requests and keep the Gunicorn timeout near its default.
- Add error_page 500 502 503 504 with a static page, so a failure shows something readable while you fix it.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
nginx 502 Bad Gateway in front of a Node.js app
connect() failed (111: Connection refused) while connecting to upstream
A 502 means nginx reached for your Node.js app and got nothing usable back.
5 causes, each with a fixServers
nginx cannot connect to the Gunicorn socket: Permission denied
502 Bad Gateway
Error 13 means the operating system refused nginx permission to open the socket file.
2 causes, each with a fixServers
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Your website on a Google Compute Engine VM times out on port 80
The site works with curl on the VM but not from outside
A timeout, as opposed to a refusal, usually means a firewall dropped the packets.
3 causes, each with a fix