Skip to content

What's the difference?

Connection refused vs timeout in Kubernetes

The same client sends two requests. One fails in a millisecond, the other after seconds. The speed of the failure tells you where to look.

Side by side

A fast no, then a long silence

Request 1 reaches pod A, where nothing listens on port 8080. The pod's own network stack sends back a reset at once: connection refused, in about a millisecond. Request 2 heads for pod B and is dropped by a NetworkPolicy on the way. Nobody replies, so the client waits its full 30 seconds: timeout.

  • request
  • reset / dropped
  • waiting
  1. Connection refusedThe pod itself lights up and answers at once. The path works; nothing is listening at the end of it.
  2. TimeoutThe CNI lights up and the request vanishes. The client's timer runs out, because no answer was ever sent.

How to tell them apart

What happened

Connection refused
Something replied: “nothing listening here”
Timeout
Nothing replied at all

How long it takes

Connection refused
Milliseconds
Timeout
The caller's whole timeout

What it proves

Connection refused
The network path to that address works
Timeout
Packets are being dropped, or the address is not reachable

Usual causes

Connection refused
Wrong targetPort, app bound to localhost, app not started, Service with no ready endpoints
Timeout
NetworkPolicy, cloud firewall or security group, stale pod IP, unreachable node

First check

Connection refused
kubectl get endpointslices for the Service, then the container's listening port
Timeout
kubectl get networkpolicy in the target namespace, then node and firewall rules

Fixed by

Connection refused
Making the port and the selector match what really runs
Timeout
Allowing the traffic, or routing it to an address that exists

In short

Connection refused vs timeout in Kubernetes: the difference

Refused: something answered “no” straight away. Timeout: nothing answered at all, and the caller gave up waiting.

A refused connection and a timeout are opposite kinds of failure. Refused means the packets arrived somewhere and that place actively said no: typically a pod with nothing listening on the port, because the Service's targetPort does not match the port the container listens on, or the app is bound to localhost only. A Service with no ready endpoints usually gives the same instant refusal. The failure is immediate, and it proves the network path works. A timeout means the packets went out and nothing came back. Something dropped them without a word: a NetworkPolicy that does not allow the traffic, a cloud firewall rule, a pod IP that no longer exists, a node that is unreachable. The caller waits for its full timeout. So the first question is how long the failure took, and the second is who would have had to answer.

Your turn

Which one is this?

Which one is this? Calls from the web namespace to the api Service hang for exactly 30 seconds and then fail. Calls from inside the api namespace work at once.

Questions

What does connection refused mean in Kubernetes?
The connection reached an address and was actively rejected, usually because nothing is listening on that port: a wrong targetPort, an app bound only to localhost, or a Service with no ready pods behind it.
What causes a connection timeout between pods?
Packets being dropped silently. The usual causes are a NetworkPolicy that does not allow the traffic, a cloud firewall or security group, or an address that no longer leads to a running pod.
Why does the speed of the failure matter?
An instant failure means something answered, so the path works and the problem is at the destination. A failure after the full timeout means nothing answered, so the problem is on the path.

Sources: Kubernetes docs: Debug Services ↗ · Kubernetes docs: Network policies ↗ · Report a problem

Diagrams are our own simulations. All wording is original and paraphrases the linked Kubernetes documentation.

Practise: diagnose the cluster

Read the terminal, watch the animation, pick the error and the first fix.

Play