Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx shows 502 Bad Gateway in front of a Django app on Gunicorn

Error502 Bad Gateway

Short 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.

  • Applies to nginx 1.26, Gunicorn (current docs), Django 5.2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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-pager
  2. 2Match what you see, then jump to its fix

    1. 1nginx 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. 2Gunicorn is active, but nginx still fails to connectnginx proxies to an address Gunicorn is not bound toFix
    3. 3502 only on slow views (reports, imports, large uploads); the Gunicorn log shows workers being restartedA slow request got its Gunicorn worker killedFix
    4. 4(13: Permission denied) while connecting to upstreamnginx may not open the Gunicorn socketFix

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-pager

2Fix

Fix the error the traceback names, then restart the unit.

sudo systemctl restart gunicorn

3Verify

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

Did this fix it?

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:application

3Verify

Test the nginx config, reload it and request the site.

sudo nginx -t && sudo systemctl reload nginx
curl -I https://example.com

Confirmed by gunicorn.org

Did this fix it?

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:application

3Verify

Repeat the slow request and confirm no worker restart shows in the log.

sudo journalctl -u gunicorn -f

Confirmed by gunicorn.org

Did this fix it?

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=0660

3Verify

Restart the socket unit and run the curl test above again.

sudo systemctl daemon-reload && sudo systemctl restart gunicorn.socket

Confirmed by gunicorn.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.