What 502 means
A server acting as a gateway or proxy (nginx, a load balancer, a CDN) tried to pass your request on, and the server behind it sent back an invalid response or none at all.
When servers send it
When the application server behind a proxy has crashed, isn’t running, refused the connection, closed it early, or sent something the proxy couldn’t understand.
Common causes
- The app process isn’t running, or crashed (and maybe is restarting).
- The proxy points at the wrong host, port or socket.
- The app closed the connection mid-response, for example running out of memory.
- Response headers too large for the proxy’s buffer (nginx: “upstream sent too big header”).
- A deploy that briefly left no healthy servers.
How to fix it as a developer
- Read the proxy’s error log: nginx says exactly what happened, such as “connect() failed (111: Connection refused) while connecting to upstream”.
- Check the app is running and listening on the address the proxy uses.
- Look at the app’s logs for crashes and out-of-memory kills at the same time.
- If headers are too big, raise
proxy_buffer_size, or send smaller cookies. - Use health checks and rolling deploys so traffic only goes to ready servers.
How to fix it as a visitor
- Reload after a minute. 502s are often brief, during a restart or deploy.
- If it lasts, the site is having problems. Try later.
Related codes
- 504 Gateway Timeout: A proxy or load balancer gave up waiting for the server behind it to reply.
- 503 Service Unavailable: The server can’t handle the request right now, usually because it’s overloaded or down for maintenance.
- 500 Internal Server Error: Something went wrong on the server, and it has no more specific code to describe it.
- 520 Web Server Returned an Unknown Error: Cloudflare reached the website’s server but got back an empty, unknown or unexpected response.
Where it’s defined
502 Bad Gateway is defined in RFC 9110, section 15.6.3. It’s a 5xx code, the server error class: the server, or something behind it, failed to deal with a valid request.
Other 5xx codes
500 Internal Server Error · 501 Not Implemented · 503 Service Unavailable · 504 Gateway Timeout · 505 HTTP Version Not Supported · 511 Network Authentication Required · 520 Web Server Returned an Unknown Error · 521 Web Server Is Down · 522 Connection Timed Out · 523 Origin Is Unreachable · 524 A Timeout Occurred · 525 SSL Handshake Failed · 526 Invalid SSL Certificate
Or search them all in the HTTP status code list.