🚨 Kubernetes Error Guide: 'no endpoints available for service' Empty Service

Exact Error Message

$ curl http://api.prod.svc.cluster.local/health
curl: (7) Failed to connect to api.prod.svc.cluster.local port 80: Connection refused

# From an Ingress controller / kube-proxy / client:
no endpoints available for service "api"

# kubectl get endpoints api -n prod
NAME   ENDPOINTS   AGE
api    <none>      12m

What the Error Means

A Kubernetes Service does not route traffic by itself — it forwards to a set of endpoints (the IP:port of each ready pod that matches the Service’s selector). The endpoint controller continuously populates Endpoints/EndpointSlice objects with the addresses of pods that (a) match the Service selector and (b) are passing their readiness probe. When that set is empty, kube-proxy, Ingress controllers, and clients have nowhere to send traffic, producing no endpoints available for service and connection refusals.

The Service exists and resolves via DNS, but it points at zero backends. The problem is almost always that no ready, label-matching pod exists — not the Service definition’s networking itself.

Common Causes

• Selector/label mismatch. The Service selector does not match any pod’s labels (a typo, a renamed label, or a version label that drifted).
• No pods are Ready. Pods exist and match, but their readiness probe is failing, so they are excluded from endpoints.
• No pods are running at all — the Deployment scaled to zero, failed to schedule, or is stuck in CrashLoopBackOff/Pending.
• A named targetPort that does not exist on the pod’s container, so the endpoint cannot be formed.
• A headless or externalName Service misconfiguration, or a Service with no selector and a manually-managed Endpoints object that is empty.
• A namespace mismatch — the Service and pods are in different namespaces.

How to Reproduce the Error

Create a Service whose selector matches nothing:

apiVersion: v1
kind: Service
metadata:
  name: api
spec:
  selector:
    app: api
    version: v2          # no pod carries version: v2
  ports:
    - port: 80
      targetPort: 8080

kubectl apply -f svc.yaml
kubectl get endpoints api
# ENDPOINTS: <none>

Diagnostic Commands

# Are there any endpoints / EndpointSlices for the service?
kubectl get endpoints <SVC> -n <NS>
kubectl get endpointslices -n <NS> -l kubernetes.io/service-name=<SVC>

# What selector does the Service use?
kubectl get svc <SVC> -n <NS> -o jsonpath='{.spec.selector}{"\n"}'

# Which pods (and labels) exist, and are they Ready?
kubectl get pods -n <NS> --show-labels
kubectl get pods -n <NS> -l app=<APP> -o wide

# Do pod labels actually match the selector?
kubectl get pods -n <NS> -l app=api,version=v2

# Why are matching pods not Ready? Check readiness probes/events
kubectl describe pod <POD> -n <NS> | grep -A4 -iE 'readiness|conditions'
kubectl get pods -n <NS> -l app=<APP> -o \
  custom-columns=NAME:.metadata.name,READY:.status.containerStatuses[*].ready

# Confirm the Service port/targetPort lines up with the container port
kubectl get svc <SVC> -n <NS> -o jsonpath='{.spec.ports}{"\n"}'
kubectl get pod <POD> -n <NS> -o jsonpath='{.spec.containers[0].ports}{"\n"}'

Step-by-Step Resolution

1. Confirm endpoints are empty and the Service selector. This separates a Service config problem from a pod problem:

kubectl get endpoints <SVC> -n <NS>
kubectl get svc <SVC> -n <NS> -o jsonpath='{.spec.selector}{"\n"}'

2. Compare the selector with actual pod labels. List pods with --show-labels and check for a match. If the selector says app=api,version=v2 but pods have app=api,version=v1, fix one side:

kubectl get pods -n <NS> --show-labels | grep api

Correct the Service selector (or the pod template labels) so they intersect.

3. If pods match but are not Ready, fix readiness. Only Ready pods become endpoints. Diagnose the failing readiness probe — wrong path, wrong port, or too-short delay:

kubectl describe pod <POD> -n <NS> | grep -A4 'Readiness'
kubectl get events -n <NS> --field-selector involvedObject.name=<POD> | grep -i readiness

Align the probe with what the app serves, or raise initialDelaySeconds.

4. If no pods exist, fix the workload. Scale up, or resolve why pods are Pending/CrashLoopBackOff:

kubectl get deploy <DEPLOY> -n <NS>
kubectl scale deploy <DEPLOY> -n <NS> --replicas=3

5. Verify port alignment. A named targetPort must match a containerPort name. Ensure the Service targetPort (number or name) matches the container’s exposed port.

6. Re-check endpoints. Once a Ready, matching pod exists, the endpoint controller fills in the addresses within seconds:

kubectl get endpoints <SVC> -n <NS> -w

Prevention and Best Practices

• Keep Service selectors minimal and stable; avoid coupling them to volatile labels like version unless you are intentionally doing blue/green routing.
• Treat readiness probes as the contract for “ready to receive traffic” — a flaky probe silently empties your endpoints.
• Use kubectl get endpoints as a first-line check whenever a Service returns connection refused.
• Validate Service targetPort against the container’s actual listening port in CI.
• Add alerts on Services with zero endpoints (via kube-state-metrics) so an empty backend set is caught before users notice.
• Keep Services and their pods in the same namespace, and reference cross-namespace traffic with fully-qualified DNS names. See more in Kubernetes & Helm guides.

Related Errors

• connection refused / context deadline exceeded — downstream symptoms of an empty or wrong endpoint set.
• Readiness probe failed — the reason matching pods are excluded from endpoints.
• default backend - 404 — an Ingress whose backend Service has no endpoints.
• FailedScheduling / CrashLoopBackOff — why the backing pods may not exist or be Ready.

Frequently Asked Questions

My DNS resolves the Service but connections are refused. Why? DNS resolution only confirms the Service object exists; it says nothing about backends. If kubectl get endpoints <SVC> shows <none>, there are no pods to route to. Fix the selector/readiness so endpoints populate.

Pods are Running but still not in the endpoints list. What is wrong? Running is not the same as Ready. Only pods passing their readiness probe become endpoints. Check the readiness probe with kubectl describe pod — a failing probe keeps a Running pod out of the Service.

I removed the readiness probe and traffic flowed — is that a fix? No, that masks the problem. Without a readiness gate, traffic can hit a pod that is not actually ready to serve. Restore the probe and fix its configuration instead.

Does a label typo really break the whole Service? Yes. The endpoint controller matches pods by exact label selector. A single mismatched key or value means zero matching pods and an empty Service. Compare kubectl get svc -o jsonpath='{.spec.selector}' with kubectl get pods --show-labels.