Error: context deadline exceeded

The “context deadline exceeded” error means a Kubernetes API operation took longer than the allowed deadline — a timeout that can hit any kubectl command.

What It Means

The client (kubectl or SDK) set a deadline for an API call, and the server did not respond before that deadline expired. This is often a client-side timeout, meaning the connection was established but the response didn’t arrive in time.

Why It Happens

• The API server is overloaded with requests and responding slowly.
• A network issue causes high latency between your client and the cluster.
• The etcd database backing the API server is slow or unhealthy.
• You’re running a kubectl get on a large cluster without pagination.
• A kubectl exec or kubectl logs command on a large pod times out.
• The --request-timeout value is too low for the operation.
• A webhook or admission controller is blocking or delaying the request.
• The client’s network connection has high packet loss.

How to Fix It

Step 1: Increase the request timeout

The default timeout for most kubectl commands is 0 (wait forever), but some commands have built-in limits. Increase it:

kubectl get pods --request-timeout=60s
kubectl get pods --request-timeout=5m

Step 2: Check API server health

If you have access to the control plane:

kubectl get componentstatuses
kubectl cluster-info

For managed clusters, check the cloud provider’s status page.

Step 3: Check etcd health

If you have SSH access to the master node:

sudo ETCDCTL_API=3 etcdctl --endpoints=localhost:2379 endpoint health

A slow etcd is the most common cause of API server latency.

Step 4: Reduce the request scope

Large requests can time out. Use pagination and filtering:

# Instead of getting all pods at once:
kubectl get pods --chunk-size=100

# Filter by label or field selector:
kubectl get pods --selector=app=myapp
kubectl get pods --field-selector=status.phase=Running

Step 5: Check for network issues

Test latency to the API server:

time kubectl get nodes
ping -c 5 <api-server>
mtr <api-server>

High latency or packet loss explains the timeout.

Step 6: Restart kubectl proxy (if using one)

If you’re using kubectl proxy:

killall kubectl-proxy
kubectl proxy --port=8080 &