How to fix 503 Service Unavailable in Kubernetes

KubernetesBEGINNERHIGHUpdated Dec 6, 2025· 203 views

The Ingress controller cannot find any healthy backend endpoints because no pods are ready, the service doesn't exist, or pod counts are zero. A 503 indicates the service has no available endpoints to route traffic to, requiring either pod startup, service creation, or endpoint verification. Fix by ensuring pods are running and ready, and verifying service endpoints exist.

Quick fix

Fixes 503 Service Unavailable

kubectl get endpoints <service-name> -n <namespace>
kubectl describe service <service-name> -n <namespace>
  1. Verify service endpoints exist
  2. Check deployment pod count
  3. List all pods for the service
  4. Verify pod labels match service selector
kubernetes — error
kubectl get endpoints <service-name> -n <namespace>
kubectl describe service <service-name> -n <namespace>
503 Service Unavailable

What this error means

A 503 Service Unavailable error from an Ingress controller means the service has no healthy endpoints. This differs from 502 (unhealthy endpoints exist) in that no endpoints are available at all. Causes include: no pods are running, all pods are not ready, the service selector doesn't match pod labels, or the backend service doesn't exist.

Typical symptoms

  • 503 Service Unavailable when accessing ingress domain
  • kubectl get endpoints shows <none>
  • No pods running for the service
  • Recently scaled to zero or deployment not yet running
  • Service selector doesn't match any pods
  • Pods exist but all are in NotReady state

Common causes

  1. No pods running or deployment hasn't started
  2. All pods are not Ready (readiness probe failing)
  3. Service doesn't exist or in different namespace
  4. Service selector doesn't match any pod labels
  5. Deployment has replicas: 0
  6. Deployment failed to create pods (image pull, resource constraints)
  7. Ingress backend references non-existent service

How to fix "503 Service Unavailable"

1Verify service endpoints exist

Check if service has any endpoints:

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

If Endpoints shows <none>, no pods are backing this service. Proceed to check pod status.

2Check deployment pod count

Verify deployment is running pods:

bash
kubectl get deployment <deployment-name> -n <namespace>
kubectl describe deployment <deployment-name> -n <namespace>

Look for "Replicas" (desired vs current). If replicas are 0 or current < desired, scale up:

bash
kubectl scale deployment <deployment-name> --replicas=2 -n <namespace>
3List all pods for the service

Find which pods should be handling traffic:

bash
kubectl get pods -n <namespace> --show-labels
kubectl get pods -n <namespace> -l <service-selector-key>=<service-selector-value>

If no pods match the service selector, the labels are wrong.

4Verify pod labels match service selector

Compare labels:

bash
kubectl get service <service-name> -n <namespace> -o yaml | grep -A3 selector
kubectl describe pod <pod-name> -n <namespace> | grep Labels

Labels must match exactly (case-sensitive, including values).

Fix with:

bash
kubectl label pod <pod-name> app=myapp -n <namespace> --overwrite
5Check pod status and readiness

Examine each pod:

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

Check:
- Phase (should be Running)
- Ready condition (should be True)
- Readiness probe status

If pods are Pending, check for scheduling issues:

bash
kubectl describe pod <pod-name> -n <namespace> | grep -A10 "Events:"
6Check deployment image and resource availability

Verify deployment can schedule pods:

bash
kubectl describe deployment <deployment-name> -n <namespace>
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20

Common issues:
- Image pull errors (wrong image, no credentials)
- Resource constraints (not enough CPU/memory)
- Node selector or affinity mismatch

Check node availability:

bash
kubectl get nodes
kubectl describe node <node-name>
7Wait for deployment rollout

If deployment was just created, pods may still be starting:

bash
kubectl rollout status deployment/<deployment-name> -n <namespace>
kubectl wait --for=condition=ready pod -l app=<label-value> --timeout=300s -n <namespace>

Wait for "deployment "..." successfully rolled out" message.

Advanced notes

A 503 can also be temporary during deployments. Use kubectl rollout status to monitor. For services with external traffic, use readiness gates or minAvailable in PodDisruptionBudget to prevent all pods going down. Distinguish between 503 (no endpoints) and 502 (bad endpoints) to troubleshoot faster. Check Ingress controller logs for exact backend status: kubectl logs -n ingress-nginx deployment/nginx-ingress-controller | grep upstream.

Frequently asked questions

What does "503 Service Unavailable" mean?
A 503 Service Unavailable error from an Ingress controller means the service has no healthy endpoints. This differs from 502 (unhealthy endpoints exist) in that no endpoints are available at all. Causes include: no pods are running, all pods are not ready, the service selector doesn't match pod labels, or the backend service doesn't exist.
How do I fix "503 Service Unavailable"?
The Ingress controller cannot find any healthy backend endpoints because no pods are ready, the service doesn't exist, or pod counts are zero. A 503 indicates the service has no available endpoints to route traffic to, requiring either pod startup, service creation, or endpoint verification. Fix by ensuring pods are running and ready, and verifying service endpoints exist.
What causes "503 Service Unavailable"?
No pods running or deployment hasn't started All pods are not Ready (readiness probe failing) Service doesn't exist or in different namespace
Is the "503 Service Unavailable" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading