How to fix headless service not found in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 96 views

A StatefulSet or Pod is trying to connect to a headless Service that does not exist or is not properly configured. This breaks DNS-based service discovery.

Quick fix

Fixes headless service not found

kubectl get svc -n your-namespace
  1. Verify the headless service exists
  2. Create the headless service
  3. Match service selector to Pod labels
  4. Test DNS resolution
kubernetes — error
kubectl get svc -n your-namespace
headless service not found

What this error means

Headless Services (with clusterIP: None) provide DNS entries for individual Pod IPs instead of a single Service IP. This is critical for StatefulSets and applications needing direct Pod-to-Pod communication. When a headless service is missing or misconfigured, DNS resolution fails and Pods cannot discover each other.

Typical symptoms

  • StatefulSet Pods cannot resolve service DNS
  • nslookup or dig fails for service domain
  • Pods get "Name or service not known" errors
  • Database cluster (e.g., Cassandra, Mongo) cannot form cluster
  • gRPC service discovery fails between Pods
  • Pod logs show "failed to resolve" messages

Common causes

  1. Headless Service was not created for the StatefulSet
  2. Service selector labels do not match Pod labels
  3. Service and Pods are in different namespaces
  4. Service was deleted but Pods still reference it
  5. Typo in service name or namespace
  6. Ingress or networking plugin blocking DNS

How to fix "headless service not found"

1Verify the headless service exists

Check if the service is created:

bash
kubectl get svc -n your-namespace

Look for the service name (typically matches the StatefulSet name). If missing, create it.

2Create the headless service

Create a headless service YAML:

yaml
apiVersion: v1
kind: Service
metadata:
  name: my-db
  namespace: default
spec:
  clusterIP: None  # This makes it headless
  selector:
    app: my-db
  ports:
  - port: 5432
    targetPort: 5432

Apply it:

bash
kubectl apply -f service.yaml
3Match service selector to Pod labels

Ensure your StatefulSet Pods have the matching labels:

yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: my-db
spec:
  serviceName: my-db  # Must match service name
  selector:
    matchLabels:
      app: my-db  # Must match service selector
  template:
    metadata:
      labels:
        app: my-db
4Test DNS resolution

From within a Pod, test if the service resolves:

bash
kubectl exec -it my-db-0 -- nslookup my-db.default.svc.cluster.local

You should get multiple A records (one per Pod). For a service with 3 replicas, you should see 3 IPs.

5Check Pod labels match service selector

Verify that running Pods have the correct labels:

bash
kubectl get pods --show-labels

Confirm all Pods have the label referenced in the service selector. If not, recreate the StatefulSet.

Advanced notes

StatefulSets require the serviceName field to be set to the headless service. The service must exist before the StatefulSet is created. For multi-zone clusters, ensure DNS is properly configured across zones. Some service meshes (Istio, Linkerd) may interfere with headless service discovery—check mesh documentation if using one.

Frequently asked questions

What does "headless service not found" mean?
Headless Services (with clusterIP: None) provide DNS entries for individual Pod IPs instead of a single Service IP. This is critical for StatefulSets and applications needing direct Pod-to-Pod communication. When a headless service is missing or misconfigured, DNS resolution fails and Pods cannot discover each other.
How do I fix "headless service not found"?
A StatefulSet or Pod is trying to connect to a headless Service that does not exist or is not properly configured. This breaks DNS-based service discovery.
What causes "headless service not found"?
Headless Service was not created for the StatefulSet Service selector labels do not match Pod labels Service and Pods are in different namespaces
Is the "headless service not found" 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