Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

kubectl installed fine, but kubectl version says the connection was refused

ErrorThe 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.

  • Applies to kubectl 1.34, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 --client
  2. 2Match what you see, then jump to its fix

    1. 1the client version prints, then the server request failskubectl version also asks the serverFix
    2. 2kubectl cluster-info fails and ~/.kube/config is missingThere is no kubeconfig for a cluster yetFix
    3. 3the server address in the error is not your clusterkubectl reads a different file or context than you expectFix
    4. 4No Auth Provider foundA managed cluster needs its authentication pluginFix

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 version

2Fix

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=yaml

3Verify

The client version prints without a server.

kubectl version --client

Confirmed by kubernetes.io

Did this fix it?

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-info

2Fix

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/config

3Verify

A URL for the control plane is printed.

kubectl cluster-info

Confirmed by kubernetes.io

Did this fix it?

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-context

2Fix

Unset a stale KUBECONFIG, or switch to the right context.

unset KUBECONFIG
kubectl config use-context my-context

3Verify

The cluster answers.

kubectl cluster-info

Confirmed by kubernetes.io

Did this fix it?

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-plugin

2Fix

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 --version

3Verify

Run a cluster command again.

kubectl cluster-info

Confirmed by kubernetes.io

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.