Kubernetes 502 Bad Gateway: Causes and Fixes Guide

Overview: Kubernetes 502 Bad Gateway

A 502 that appears only after a deployment, during a traffic spike, or on one route is rarely a browser problem. It means a gateway received the request, attempted to reach an upstream workload, and could not obtain a valid response. In Kubernetes, that upstream may be an ingress controller, a Service endpoint, a pod, or another proxy in the service mesh. The fastest path to a fix is to identify which hop stopped returning a usable response instead of restarting every component in the cluster.

A kubernetes 502 bad gateway error most often comes from unhealthy backend pods, incorrect Service selectors that leave no valid endpoints. Ingress configuration errors, or readiness probe failures that route traffic before an application can serve it. Service-mesh timeout, retry, mTLS, and connection-pool settings can produce the same symptom. Start with the gateway logs, then verify pod readiness and the endpoints behind the Service.

The distinction matters because each failure leaves different evidence. A terminating pod can remain in an endpoint slice briefly. While an application that binds only to localhost may be reachable from inside its container but not through the Service. During a rolling update, graceful shutdown and an adequate termination grace period also determine whether existing requests finish or become connection resets. Kubernetes readiness probes are designed to keep traffic away from pods that are not ready. But a probe can still be wrong for the application it is meant to protect. Before changing timeouts or adding retries, establish what a 502 represents at the gateway and where the upstream response became invalid. That model makes the rest of the diagnosis deliberate rather than speculative.

Learn how Plural's AI-native fleet control plane turns 502 debugging into a single-pane-of-glass task.

What Does a 502 Bad Gateway Error Mean in Kubernetes?

A Kubernetes 502 Bad Gateway error means that a gateway or proxy received an invalid response from the upstream application it was trying to reach. In a typical cluster, the gateway is an Ingress controller. In a service-mesh deployment, it may be a sidecar proxy. The upstream is usually a backend pod reached through a Kubernetes Service. The proxy is therefore reporting a failure in the request path, not necessarily reporting that the pod is completely down.

The distinction matters when troubleshooting. A pod can be Running and still produce a 502 if its application is not accepting connections. Is listening on the wrong port, closes the connection before returning a response, or sends an HTTP response the proxy cannot parse. An application that binds only to 127.0.0.1, for example, may respond to requests inside its own container while remaining unreachable through the pod network. The backend must bind to an address that accepts traffic from the network, such as 0.0.0.0. Kubernetes Services and their selectors then determine which pods receive that traffic. See the Kubernetes documentation on Services and service networking for the underlying model.

From the gateway's perspective, several conditions can look the same:

The connection to the backend is refused because the process has crashed, is not listening, or the Service targets the wrong port.
The backend does not respond before the gateway's timeout, often because the application is overloaded, blocked, or handling a long-running request.
The backend closes the connection prematurely, including while a pod is terminating during a rollout.
The backend sends malformed or incomplete HTTP, such as an improperly formatted response or missing required headers.

That is why a 502 is not synonymous with "the pod is down." It identifies the boundary where the gateway received something unusable from upstream. The root cause may be in the application, the Service and endpoint mapping, the Ingress configuration, or the mesh policy between proxies. During termination, a pod can also remain temporarily available in an endpoint set while the Ingress controller updates its routing state, creating intermittent 502 responses. Kubernetes documents this Service and endpoint behavior at kubernetes.io.

Start with the component that returned the status, then trace one request toward the backend: gateway logs, Service, endpoints, pod readiness, listening port, and application logs. This separates a routing problem from an application response problem and prevents an unnecessary restart from obscuring the actual failure.

Causes of Kubernetes 502 Bad Gateway Errors

A kubernetes 502 bad gateway response usually means the proxy reached the routing layer but could not obtain a valid response from the selected upstream. The failure may sit in the application, the Service configuration, the Ingress object, or a service mesh between them. Treat the 502 as a routing and upstream-health signal, not as proof that the Ingress controller itself is broken.

Common causes of Kubernetes 502 responses
Cause	Typical symptom	How to spot it
Unhealthy backend pods	Intermittent or persistent 502s, often alongside restarts, `CrashLoopBackOff`, `OOMKilled`, refused connections, or exhausted application threads and connection pools.	Run `kubectl get pods` and inspect `kubectl describe pod`. Check container logs, restart counts, termination reasons, memory limits, and application concurrency metrics. An OOMKill can terminate a busy pod before the proxy receives a response. Review resource limits when memory pressure is involved.
Incorrect Service selector	The Service exists, but it has no usable endpoints, or traffic reaches pods belonging to the wrong workload.	Compare the Service selector with pod labels, then run `kubectl get endpoints <service>` and `kubectl get endpointslice`. Kubernetes Services route only to matching labels. Use debugging service endpoints to confirm the selected addresses and ports.
Ingress port or rule misconfiguration	One host or path returns 502 while others work. The controller may route to the wrong backend, a port with no listener, or a conflicting rule.	Inspect `kubectl describe ingress`. Verify that the Ingress backend port matches the Service port and that the Service `targetPort` reaches the port the container actually exposes. Also check for overlapping host and path rules. A process bound to `localhost` instead of `0.0.0.0` can produce the same symptom.
Readiness probe failure	New or restarting pods appear Running but do not receive reliable traffic. During deploys, the available backend set may briefly become empty.	Check `kubectl get pods` for `0/` readiness and inspect probe events with `kubectl describe pod`. Readiness probes are intended to keep traffic away from pods that have not finished starting. So a wrong path, port, credentials check, or startup threshold can remove healthy-looking pods from service routing.
NetworkPolicy or service mesh failure	The Service and endpoints look correct, but the proxy cannot connect. Mesh users may see mTLS negotiation failures, Envoy upstream errors, exhausted connection pools, or sidecars unable to reach their control plane.	Confirm NetworkPolicies allow the Ingress controller to reach backend pods. Then inspect sidecar and proxy logs, mTLS policy, clusters, routes, and connection-pool counters. Trace the request through the mesh rather than debugging only the application container.
Timeout or graceful-shutdown mismatch	Only slow requests, long-running work, or rolling updates produce 502s. Short requests continue to succeed.	Compare Ingress, mesh, load-balancer, and application timeouts. Check whether thread or database connection pools are saturated. During termination, verify that the application handles SIGTERM and that the endpoint removal and shutdown grace period allow active requests to finish.

Start with the failing request's host and path, then follow the chain from Ingress logs to Service endpoints and finally to the pod or sidecar. That narrows a broad Kubernetes 502 bad gateway symptom into a specific configuration, health, or capacity failure.

How a Kubernetes 502 Error Flows Through Ingress, Services, and Endpoints

A request that ends as a kubernetes 502 bad gateway response has usually crossed several routing boundaries. The client connects to the Ingress controller, the controller selects a Kubernetes Service. The Service resolves to an EndpointSlice, and the selected pod must accept the connection and return a valid HTTP response. A failure at any boundary can look identical from the client side, even though the corrective action differs.

Client to ingress controller

The client first reaches the external load balancer or Ingress controller. The controller matches the host and path against its Ingress rules, then proxies the request upstream. A wrong host rule, conflicting path, unavailable controller, or backend port mismatch can prevent the request from reaching the intended application. Start with the controller logs and the Ingress definition when the response is generated at this hop. The troubleshooting ingress controllers guide covers the objects and events to inspect.

Ingress controller to Service

The Ingress backend points to a Service port, not directly to a deployment. The Service then uses its selector to find pods whose labels match the selector. For example, a selector such as app: checkout will only include pods carrying that exact label. A typo, changed label, or selector copied from another workload can leave the Service with no usable backends. Confirm the port named by the Ingress, the Service's port and targetPort, and the port on which the container is actually listening. See the Kubernetes services configuration guide for the relationship between these fields.

Service to EndpointSlice to pod

The control plane's EndpointSlice controller watches Services and matching pods, then maintains the EndpointSlice objects that describe eligible backend addresses. The Ingress controller watches that data and builds its routing table. You can use kubectl get endpoints and inspect EndpointSlices to verify whether the expected pod IPs are present. This is the practical starting point for debugging service endpoints.

Staleness is especially visible during rollouts. A pod may be terminating while its address remains briefly in an EndpointSlice or in the Ingress controller's in-memory routing table. The controller can send a request to that address after the application has stopped accepting connections, producing a temporary 502. The application should handle SIGTERM gracefully, finish active requests, and use an appropriate terminationGracePeriodSeconds. If the grace period expires, Kubernetes sends SIGKILL, which can cut connections abruptly. This lifecycle behavior is documented in the Kubernetes pod lifecycle documentation.

Network policy and backend reachability

Even with correct labels and current endpoints, the controller must be able to connect to the pod over the cluster network. A NetworkPolicy that permits client traffic but denies ingress-controller-to-backend traffic will produce connection failures at the proxy layer. Check that the policy allows traffic from the Ingress controller's namespace or pod identity to the backend port. Also verify the datapath through kube-proxy networking fundamentals when Service forwarding behaves differently from direct pod access. Mapping the request one hop at a time separates a stale route, a selector error, and a blocked connection before you change the application itself.

See how centralized observability across clusters helps you find the failing hop before a 502 reaches users.

How to Diagnose a Kubernetes 502 Bad Gateway Error

Use a fixed request path instead of changing several resources at once. Capture the failing URL, namespace, service, and timestamp, then work from the edge toward the application. This sequence separates an ingress routing problem from an empty endpoint set, an unready pod, a port mismatch, a network policy denial, or a service mesh failure.

Reproduce the failure and capture timing. Send the same request with a known method and path, and record the response code, response headers, request ID, client location, and UTC timestamp. If the failure is intermittent, run several requests during the incident and compare them with deployment or pod restart times. A timestamp lets you correlate the request with controller logs and Kubernetes events. Avoid testing only from inside the backend pod, because that can bypass the ingress and network path where the 502 is generated.
Read the ingress controller logs. Start with the controller handling the request, commonly in the ingress-nginx namespace:
Filter for the host, path, request ID, or timestamp. Look for messages such as connection refused, upstream timed out, no live upstreams, or an invalid response. These messages are usually the fastest way to identify why the proxy returned a 502. The controller logs are the primary diagnostic source for a request-specific failure. For a broader guide, see troubleshooting ingress controllers.
Verify the Service endpoints. Check whether the Service has any ready backend addresses:
Compare the addresses and ports with the pods you expect to receive traffic. An empty endpoint set commonly means the selector does not match pod labels, or that readiness checks have removed every pod from serving traffic. The endpoint view is useful for debugging service endpoints. If endpoints exist but point to terminating or unexpected pods, correlate the result with the rollout timeline.
Check pod readiness and recent events. Inspect status, node placement, readiness conditions, restarts, probe failures, and scheduling warnings:
Read the Events section, then check the application container logs. A pod can be Running while still failing its readiness probe, so Running alone does not prove that it can serve requests. Confirm that the probe path, port, startup timing, and response are correct. Readiness probes are intended to keep traffic away from an application until it is ready to serve.
Validate every port in the route. Trace the port from the Ingress backend to the Service, from the Service target port to the container, and from the container to the process actually listening. The Ingress should reference the Service port, while the Service target port must resolve to the port exposed by the pod. Check the manifests and test the listening address when possible. A process bound only to 127.0.0.1 can fail even when the numeric port appears correct. A port mismatch is a primary 502 troubleshooting path, especially when a Service defines multiple target ports.
Check NetworkPolicies. Review policies in both the ingress and application namespaces. Confirm that ingress controller pods are allowed to connect to the backend pod labels and destination port. And that the response path is not blocked by an egress rule. A policy denial can look like a refused or timed-out upstream connection even though the pods and endpoints are healthy.
Trace through any service mesh. If sidecars are injected, test the proxy path as well as the application path. Inspect sidecar logs and proxy clusters, endpoints, connection failures, retries, and timeouts. Verify that the sidecar is healthy and connected to the mesh control plane. Also check mTLS policy compatibility between caller and backend. A service mesh misconfiguration, including a failed sidecar-to-control-plane connection or incompatible mTLS settings, can produce persistent 502 responses. Resolve the first failing hop rather than increasing retries blindly.

kubectl get pods -n <namespace> -o wide
kubectl describe pod <pod-name> -n <namespace>

kubectl get endpoints <service-name> -n <namespace>
kubectl describe service <service-name> -n <namespace>

kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --since=10m

How to Fix a Kubernetes 502 Bad Gateway Error

Fix the failure at the first boundary that cannot establish a valid upstream connection. Start with the Service and its endpoints, then verify pod readiness, proxy behavior, shutdown timing, ingress capacity, and mesh health. Each layer should have one clear contract with the next.

Correct the Service selector and target port

A Service routes traffic only to pods whose labels match its selector. Confirm that the Ingress points to the Service port, and that targetPort matches the port where the application is actually listening. The Kubernetes documentation describes labels and selectors as the link between a Service and its backend pods.

apiVersion: v1
kind: Service
metadata:
  name: registry-api
spec:
  selector:
    app: registry-api
  ports:
    - port: 80
      targetPort: 8080

Then compare the selector with kubectl get pods --show-labels and inspect kubectl get endpoints registry-api. An empty or unexpected endpoint set means the proxy has nowhere valid to send the request. See this guide to debugging service endpoints when the values do not line up. Sources: Kubernetes Services and Ingress configuration.

Gate traffic on readiness, not process startup

A running container is not necessarily ready to serve HTTP. Add a readiness probe for the application health endpoint, and use a readiness gate when an external controller must report an additional condition before traffic is safe.

readinessProbe:
  httpGet:
    path: /readyz
    port: 8080
  periodSeconds: 5
  failureThreshold: 3

For workloads that depend on a sidecar, load step, or registration event, configure podReadinessGates so the pod remains out of service endpoints until that condition is true. Readiness probes and gates prevent startup races that commonly surface as a Kubernetes 502 Bad Gateway. See the Kubernetes pod lifecycle documentation.

Tune timeouts and retry only safe requests

Long-running requests can exceed the ingress proxy's read timeout even when the application is healthy. For ingress-nginx, set proxy-read-timeout at the Ingress when the endpoint legitimately needs more time. Retries can hide a transient upstream failure, but restrict them to idempotent operations such as GET. Retrying a POST without an idempotency strategy can duplicate work.

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
    nginx.ingress.kubernetes.io/proxy-next-upstream: "error timeout http_502"

Validate the timeout against the application's own request and load-balancer limits. The ingress-nginx annotation reference documents proxy timeout tuning.

Drain connections during rolling updates

Pods can remain in an endpoint set briefly while terminating. Give the application time to handle SIGTERM, remove it from traffic, and finish active requests before Kubernetes sends SIGKILL. A preStop hook and a sufficient grace period reduce dropped connections during redeployments.

spec:
  terminationGracePeriodSeconds: 45
  containers:
    - name: api
      lifecycle:
        preStop:
          exec:
            command: ["/bin/sh", "-c", "sleep 10"]

Use a measured drain interval rather than copying these values blindly. The relevant references are the container lifecycle hooks and pod lifecycle guides.

Remove capacity and service-mesh bottlenecks

If routes, endpoints, and probes are correct, inspect ingress saturation. An ingress controller connection pool can exhaust under high concurrency; increase CPU and memory appropriately, and add replicas behind a load balancer. Persistent 502s in a mesh require the same boundary check: verify mTLS policy compatibility, sidecar health, upstream cluster configuration, and connection-pool limits. A sidecar that cannot reach its control plane or cannot establish mTLS can return the error before the application receives anything. Check mesh telemetry alongside ingress logs, and consult Istio's traffic-management documentation for policy and routing behavior.

Preventing 502 Errors Across a Kubernetes Fleet

Reliable prevention starts before an incident reaches the ingress controller. Standardize the contract between every workload, Service, and proxy so that a deployment behaves predictably in every cluster. Readiness probes should verify that the application can actually serve its dependency set, not merely that its process is running. Kubernetes uses readiness to decide whether a pod should receive traffic, which prevents cold or partially initialized replicas from entering the load-balancing pool. See the Kubernetes pod lifecycle documentation when defining probe behavior and startup sequencing.

Make health and capacity checks part of the platform baseline

Apply consistent readiness and liveness probe conventions through shared manifests or policy. Give applications enough startup time, and use a startup probe when initialization is materially longer than steady-state health checks. A probe that is too aggressive can remove healthy-but-busy pods; one that is too shallow can leave an application in service while it cannot answer requests.

Resource settings are equally important. Tune memory limits against observed peak usage and leave enough headroom for normal concurrency. For high-traffic services, an undersized limit can trigger an OOMKill, terminate the backend, and leave the ingress with no usable upstream. Factoring requests and limits into workload reviews also makes autoscaling decisions more predictable. At the edge, monitor ingress replica CPU, memory, active connections, and connection-pool saturation. Large fleets may need additional ingress replicas or higher resource allocation when the controller's connection pool becomes saturated.

Make deployments drain connections instead of dropping them

Rolling deployments should combine readiness transitions with graceful shutdown. A preStop hook can begin application draining, while an appropriate terminationGracePeriodSeconds gives active requests time to finish. Pods that terminate too quickly can remain in the ingress routing view briefly, producing a spike of 502 responses before endpoint data catches up. Validate this behavior in a staging cluster under live-like traffic, then standardize the deployment pattern across environments.

Set ingress and service-mesh timeouts to match the actual request profile. Use retries selectively for idempotent requests, since retrying writes can duplicate side effects. Document which layer owns each timeout and retry policy, and alert when retries rise rather than treating them as invisible recovery. This makes a temporary upstream fault visible before it becomes an availability incident.

Observe the fleet as one system

Centralized telemetry should correlate ingress status codes with Service endpoints, pod readiness, restarts, OOMKills, and mesh response details. That context distinguishes an application failure from a routing or proxy failure quickly. Plural's AI-native unified control plane provides a single pane of glass for fleet observability and day-2 operations. Helping platform teams compare behavior across clusters and narrow root cause before users encounter a Kubernetes 502 Bad Gateway. Its self-hosted, agent-based pull architecture also keeps cluster-specific connectivity issues scoped to the affected environment while giving operators centralized operational context.

Use these signals to define a fleet-wide 502 SLO, then test it with controlled rollouts and dependency failures. Prevention is not one ingress annotation. It is a repeatable workload, deployment, networking, and observability standard applied consistently across every cluster.

Explore Plural's self-hosted, agent-based platform for fleet-wide Kubernetes reliability.

Frequently Asked Questions

What causes a 502 Bad Gateway error in Kubernetes?

A 502 means a gateway or proxy received an invalid response from an upstream server. In Kubernetes, common causes include unhealthy or unready pods, a Service selector that matches no pods, incorrect ingress configuration, and service mesh timeouts or retry settings. Start by identifying which proxy returned the error, then verify the backend endpoints and the application response.

How do I fix a 502 Bad Gateway in Nginx Ingress?

Confirm that the Ingress points to the correct Service and port, then run kubectl get endpoints <service-name>. The Service should list ready pod addresses. If it has no endpoints, check the selector labels and pod readiness. If endpoints exist, inspect Nginx Ingress logs and test the backend from inside the cluster to distinguish a routing problem from an application or network failure.

Does a Kubernetes 502 Bad Gateway error mean the pod is down?

Not necessarily. A pod may be running but fail its readiness probe, listen on a different port, return malformed or prematurely closed responses, or exceed a proxy timeout. Check both pod status and readiness conditions with kubectl get pods and kubectl describe pod. A healthy process is not automatically a reachable, ready upstream.

Why does an ingress controller return 502 intermittently?

Intermittent errors usually point to an unstable subset of backends, uneven readiness, connection resets, or timeout and retry settings that do not match application latency. Compare successful and failing pods, review ingress and mesh logs by timestamp, and inspect endpoint changes during an incident. Fix the unhealthy backend or configuration before increasing retries, since retries can amplify load on a failing service.

Ready to reduce recurring 502 errors across your clusters?

Once you have traced an error to its ingress, service, or mesh boundary, consistent visibility across clusters can make the next investigation more direct. Plural brings fleet observability into one place so platform teams can connect symptoms with the Kubernetes resources behind them.

Get started with Plural's AI-native Kubernetes fleet management platform.