How to fix connect: connection refused in Kubernetes

KubernetesINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 289 views

A pod cannot connect to a service because the service port is wrong, the application isn't listening, or there are no healthy endpoints. The connection is refused at the network level, typically because the service has no running pods or the pod is listening on a different port than configured. Fix by verifying endpoints, application ports, and readiness probes.

Quick fix

Fixes connect: connection refused

kubectl get endpoints <service-name> -n <namespace>
kubectl describe service <service-name> -n <namespace>
  1. Check service endpoints
  2. Verify pod labels match service selector
  3. Check pod readiness status
  4. Verify service port matches container port
kubernetes — error
kubectl get endpoints <service-name> -n <namespace>
kubectl describe service <service-name> -n <namespace>
connect: connection refused

What this error means

When a client tries to connect to a service, Kubernetes routes traffic to endpoints (backend pods). Connection refused occurs when no endpoints exist (pods down/not ready), the pod listens on a different port, or the service targets the wrong port. Unlike DNS failures, the connection reaches the pod but the pod refuses it.

Typical symptoms

  • Client connection fails immediately with "connection refused"
  • curl or telnet to service IP times out or refuses
  • Service exists but traffic doesn't reach pods
  • Endpoints show empty or mismatched pods
  • Works when connecting to pod IP directly but not service IP
  • Port forward works but service access fails

Common causes

  1. Service port doesn't match container port
  2. Application not listening on expected port
  3. No healthy endpoints (pods not running or not ready)
  4. Readiness probe failing, marking pod as not ready
  5. Pod port exposed in Dockerfile but not in service spec
  6. Selector in service doesn't match pod labels
  7. Traffic policy (ClientIP vs Cluster) causing routing issues

How to fix "connect: connection refused"

1Check service endpoints

Verify service has running, ready pods:

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

Look at the Endpoints field. If it shows <none>, no pods match the selector or all are not ready.

2Verify pod labels match service selector

Service selector must match pod labels exactly (case-sensitive):

bash
kubectl get pods --show-labels -n <namespace>
kubectl describe service <service-name> -n <namespace> | grep -i selector

Ensure pod labels include all key=value pairs from service selector.

3Check pod readiness status

Pods must be Ready for traffic to reach them:

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

If status is not Running or Ready is False, the pod won't receive traffic. Check readiness probe configuration and logs.

4Verify service port matches container port

Service and pod port must align:

bash
kubectl get service <service-name> -n <namespace> -o yaml | grep -A5 ports
kubectl get pod <pod-name> -n <namespace> -o yaml | grep -A3 containerPort

Example:

yaml
# Service
ports:
- port: 80          # External port
  targetPort: 8080  # Container port

# Pod
containerPort: 8080
5Test application is listening on expected port

Connect to pod directly and check if port is listening:

bash
kubectl exec -it <pod-name> -n <namespace> -- sh
netstat -tlnp | grep <port>
# or
lsof -i :<port>

If port not listed, the application isn't listening. Check application logs and startup configuration.

6Check readiness probe configuration

Failing readiness probes remove pods from endpoints:

bash
kubectl describe pod <pod-name> -n <namespace> | grep -A5 "Readiness"
kubectl logs <pod-name> -n <namespace>

If readiness probe is too strict or has wrong port/path, pods won't be marked as ready. Adjust timeoutSeconds, initialDelaySeconds, or probe path.

7Test port-forward to isolate the issue

Use port-forward to bypass service routing:

bash
kubectl port-forward pod/<pod-name> 8080:8080 -n <namespace> &
curl localhost:8080/health

If port-forward works but service doesn't, the issue is service routing/endpoints, not the application.

Advanced notes

Service discovery happens via CoreDNS; connection refused is a networking issue, not DNS. Use tcpdump on nodes to capture traffic: tcpdump -i any -n port 8080. For debugging without altering pods, use kubectl logs and kubectl exec. Headless services (clusterIP: None) bypass service IP and connect directly to pod IPs, useful for StatefulSets. Session affinity (clientIP) can appear to break connectivity if not configured correctly.

Frequently asked questions

What does "connect: connection refused" mean?
When a client tries to connect to a service, Kubernetes routes traffic to endpoints (backend pods). Connection refused occurs when no endpoints exist (pods down/not ready), the pod listens on a different port, or the service targets the wrong port. Unlike DNS failures, the connection reaches the pod but the pod refuses it.
How do I fix "connect: connection refused"?
A pod cannot connect to a service because the service port is wrong, the application isn't listening, or there are no healthy endpoints. The connection is refused at the network level, typically because the service has no running pods or the pod is listening on a different port than configured. Fix by verifying endpoints, application ports, and readiness probes.
What causes "connect: connection refused"?
Service port doesn't match container port Application not listening on expected port No healthy endpoints (pods not running or not ready)
Is the "connect: connection refused" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading