kubectl: unable to connect to the server

Fix kubectl "unable to connect to the server" by checking kubeconfig context, API server reachability, and credential expiration.

beginnerdebuggingkuberneteskubectlnetwork

Symptoms

The connection to the server <host>:6443 was refused
unable to connect to the server: dial tcp ...: i/o timeout
kubectl works for a colleague but not for you

Possible causes

The current context points at the wrong cluster or endpoint
The API server endpoint is unreachable from your network
Client credentials or the certificate have expired
kubeconfig paths or permissions are wrong

Diagnosis steps

Inspect the active context and server address

kubectl config current-context && kubectl config view --minify

Interpretation

Confirm the endpoint and user match the cluster you intend to reach.

Test TCP reachability to the API port

nc -vz <host> 6443

Interpretation

A refusal means nothing listens or a firewall blocks; a timeout means routing or a dropped packet.

Check client certificate validity

Interpretation

Expired client certs fail authentication after connecting, often reported as a connection error.

Root cause

This error spans two failure points: the client cannot establish a connection to the API endpoint (wrong context, network, or firewall), or it connects but authentication fails because credentials or certificates expired. kubeconfig selects the endpoint and credentials, so a wrong or stale context is a frequent cause.

Fix

Set the correct context with kubectl config use-context, verify the endpoint is reachable, and refresh expired credentials or certificates. Fix kubeconfig file paths and permissions, and ensure proxies or VPNs are active when the cluster is on a private network.

Verify the fix

Run `kubectl cluster-info` and `kubectl get nodes`; both succeed, listing the API server and nodes, confirming the context, network, and credentials are all valid.

Symptoms

kubectl reports The connection to the server ... was refused or a dial timeout. Often it works from another machine, which points at local configuration or network.

Diagnosis

Check the context and reachability:

kubectl config current-context
kubectl config view --minify
nc -vz api.cluster.internal 6443

A wrong server address or an expired client certificate both manifest here.

Fix

Select the right context and refresh credentials:

kubectl config use-context prod
kubectl cluster-info

Renew client certificates or tokens and verify kubeconfig permissions.

Verification

kubectl get nodes returns the node list; the API server is reachable and authentication succeeds, confirming the context, network, and credentials are aligned.

Two Failures Behind One Message

The single “unable to connect” message covers both a transport failure and an authentication failure, and mixing them up wastes time. A refusal or timeout means packets never reached a working API server, so the fix is context selection, VPN or bastion access, or firewall rules. A connected-then-rejected handshake usually means expired credentials or a certificate that no longer matches the cluster, which requires a kubeconfig refresh rather than a network change. Testing with nc or openssl against the API port separates the two cases in seconds and points directly at the right fix.