kubectl installed fine, but kubectl version says the connection was refused
The connection to the server <server-name:port> was refused - did you specify the right host or port?Short answer
kubectl version asks the cluster as well as the client, so with no reachable cluster it fails even when the install is fine. Prove the install with kubectl version --client, then check your kubeconfig, active context and cluster address with kubectl config and kubectl cluster-info.
Fix it fast
1Find out which cause you have
Ask for the client version only. If this works, the binary is installed correctly and the problem is cluster access.
kubectl version --client2Match what you see, then jump to its fix
- 1
the client version prints, then the server request failskubectl version also asks the serverFix - 2
kubectl cluster-info fails and ~/.kube/config is missingThere is no kubeconfig for a cluster yetFix - 3
the server address in the error is not your clusterkubectl reads a different file or context than you expectFix - 4
No Auth Provider foundA managed cluster needs its authentication pluginFix
- 1
What does the error look like?
The connection to the server <server-name:port> was refused - did you specify the right host or port?No Auth Provider found
Cause 1 of 4
kubectl version also asks the server
1Check
Without --client, kubectl version prints client and server information for the current context. No reachable cluster means a refused connection even when the binary is fine.
kubectl version2Fix
Use --client when you only want to prove the install. Use kubectl cluster-info when you want to prove cluster access.
kubectl version --client --output=yaml3Verify
The client version prints without a server.
kubectl version --clientConfirmed by kubernetes.io
Cause 2 of 4
There is no kubeconfig for a cluster yet
1Check
kubectl needs a kubeconfig file to find a cluster; by default it is ~/.kube/config. A fresh install has none, and it is created only when you create or join a cluster.
ls -l ~/.kube/config
kubectl cluster-info2Fix
Create a cluster, for example a local one with Minikube, or copy the kubeconfig your cluster provider gives you to ~/.kube/config.
mkdir -p ~/.kube
cp /path/from/provider/config ~/.kube/config3Verify
A URL for the control plane is printed.
kubectl cluster-infoConfirmed by kubernetes.io
Cause 3 of 4
kubectl reads a different file or context than you expect
1Check
kubectl loads --kubeconfig first, then the files in $KUBECONFIG, then ~/.kube/config. Print what it merged and the active context.
echo "$KUBECONFIG"
kubectl config view
kubectl config current-context2Fix
Unset a stale KUBECONFIG, or switch to the right context.
unset KUBECONFIG
kubectl config use-context my-context3Verify
The cluster answers.
kubectl cluster-infoConfirmed by kubernetes.io
Cause 4 of 4
A managed cluster needs its authentication plugin
1Check
Since Kubernetes 1.26 kubectl no longer has built-in authentication for the managed offerings of Azure and Google. They ship kubectl plugins instead.
which kubelogin gke-gcloud-auth-plugin2Fix
Install the provider's plugin: kubelogin for Azure AKS, gke-gcloud-auth-plugin for Google Kubernetes Engine. Follow the provider's own instructions for it.
gke-gcloud-auth-plugin --version3Verify
Run a cluster command again.
kubectl cluster-infoConfirmed by kubernetes.io
How do I stop it coming back?
- Use kubectl version --client to check an install, not kubectl version.
- Keep one kubeconfig per cluster and name your contexts clearly.
- Do not export KUBECONFIG in a shell profile unless you need it.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Servers
kubectl cannot reach the Kubernetes API server on port 6443
dial tcp <ip>:6443: connect: connection refused
Port 6443 is the Kubernetes API server.
3 causes, each with a fixServers
dnf cannot install MySQL on Amazon Linux 2023
dnf cannot find a mysql-server package on Amazon Linux 2023
Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.
3 causes, each with a fixServers
Ansible hangs, then times out waiting for the sudo prompt
a playbook using become seems to hang
Ansible ran sudo on the target and never saw the answer it expected.
3 causes, each with a fixServers
Apache on Ubuntu returns 404 Not Found for my site
The requested URL was not found on this server.
On Ubuntu a 404 from Apache usually means the request maps to a path that has no file.
3 causes, each with a fixServers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix