502, 503 and 504 Errors From Your Container

A 5xx response served in front of your HTTP container almost always means there is no healthy replica to send the request to, or your application is too slow to respond. These errors come from the layer that sits in front of your container, so they can appear even when the container itself is up.

Symptoms

• Requests to your container return 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout.
• The errors are intermittent under load, or constant right after a deploy.
• The default hostname or a custom domain returns an error page instead of your application.

Likely causes

• The application isn't listening on the configured port. If the app binds to a different port, or to localhost instead of 0.0.0.0, requests can't reach it.
• The health check is failing, so there are no healthy replicas. With nothing healthy to route to, the ingress layer returns a 503.
• The application is slow. Requests that take longer than the gateway will wait return a 504.
• The process crashed or is restarting, so requests arrive while no replica is ready.
• The container is under-provisioned and can't keep up with the request volume, so replicas become unresponsive.

How to fix

1. Confirm the port and bind address. The application must listen on the configured container port and bind to 0.0.0.0, not localhost.
2. Check that replicas are healthy. If the health check is failing, no traffic can be served. Verify the health check path returns a 2xx response. See Health Check Failures.
3. Read the gateway logs. The Observability section on the container detail page records every request, including its response status and the gateway/upstream latency breakdown. This tells you whether the delay is in the gateway or your application.
4. Read the application logs for crashes, timeouts, or slow queries around the time of the errors.
5. Raise resources or add replicas if the container is overloaded. Increasing CPU and memory, or enabling autoscaling with a higher maximum, gives the container more headroom. See Resources and Scaling.
6. Check for memory pressure. A replica being killed for running out of memory presents as intermittent 5xx errors under load. See Container Out of Memory.

Related

• Health Check Failures
• Container Out of Memory
• Resources and Scaling
• HTTP Containers