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
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
- Connection refusedThe pod itself lights up and answers at once. The path works; nothing is listening at the end of it.
- 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
| Question | Connection refused | Timeout |
|---|---|---|
| What happened | Something replied: “nothing listening here” | Nothing replied at all |
| How long it takes | Milliseconds | The caller's whole timeout |
| What it proves | The network path to that address works | Packets are being dropped, or the address is not reachable |
| Usual causes | Wrong targetPort, app bound to localhost, app not started, Service with no ready endpoints | NetworkPolicy, cloud firewall or security group, stale pod IP, unreachable node |
| First check | kubectl get endpointslices for the Service, then the container's listening port | kubectl get networkpolicy in the target namespace, then node and firewall rules |
| Fixed by | Making the port and the selector match what really runs | Allowing the traffic, or routing it to an address that exists |
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.
Related errors
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.