kubectl "Unable to connect to the server: dial tcp ... i/o timeout"

By Daniel Zoghalchali·Latchkey

kubectl could not even open a TCP connection to the API server. dial tcp <ip>:443: i/o timeout means the endpoint is unreachable from the runner - a network path, security group, private-endpoint, or VPN problem rather than auth.

What this error means

kubectl hangs then fails with Unable to connect to the server: dial tcp <ip>:<port>: i/o timeout. It is a connectivity failure - the request never reached the server, so auth/RBAC are not even in play.

Unable to connect to the server: dial tcp 10.0.12.34:443: i/o timeout

Diagnose it: read events, not just status

A deployment that never becomes ready has the reason in its events and in the pod state, not in the deployment status. Read both before changing the manifest.

kubectl rollout status deploy/<name> --timeout=120s
kubectl describe deploy/<name> | sed -n "/Events/,$p"
kubectl get pods -l app=<name> -o wide
kubectl describe pod <pod> | sed -n "/Events/,$p"
kubectl logs <pod> --previous --tail=50   # the crash before the restart

Common causes

Runner has no network path to the API server

A private EKS/GKE endpoint, a missing VPN/peering, or a security group/firewall that does not allow the runner’s egress to the API port leaves the connection timing out.

Stale or wrong endpoint

The kubeconfig points at an old load-balancer IP or a cluster that moved/was recreated, so the address no longer routes.

Transient network blip

A brief network interruption can cause a one-off timeout that clears on retry.

How to fix it

Confirm reachability of the endpoint

Find the server address and test the TCP path independently of kubectl.

kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'; echo
nc -vz <api-host> 443

Fix the network path or endpoint

1. For a private cluster, run CI from inside the VPC/VPN, or add the runner CIDR to the API allowlist/security group.
2. Regenerate the kubeconfig after any cluster recreation (aws eks update-kubeconfig / gcloud ... get-credentials).
3. Wrap the call in a bounded retry to ride out a transient blip.

for i in 1 2 3; do kubectl get ns --request-timeout=20s && break; sleep $((i*5)); done

How to prevent it

• Run CI runners where they can reach the cluster API (VPC/VPN/allowlist).
• Regenerate kubeconfig endpoints after cluster changes.
• Add a bounded retry around the first cluster call to absorb transient timeouts.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation