kubectl "The connection to the server was refused" in CI

By Kaveh Alemi·Latchkey

kubectl is trying to reach localhost:8080 - its default when no kubeconfig is configured. In CI this almost always means credentials were never provided, so kubectl is talking to nothing.

What this error means

kubectl fails with The connection to the server localhost:8080 was refused - did you specify the right host or port?. The tell is localhost:8080: kubectl has no cluster configured at all.

The connection to the server localhost:8080 was refused - did you specify the
right host or port?

Common causes

No kubeconfig provided

KUBECONFIG is unset and ~/.kube/config is empty/absent, so kubectl falls back to the legacy localhost:8080 default - where nothing is listening.

Credential generation step failed silently

A get-credentials/update-kubeconfig step failed or wrote to a path kubectl is not reading, leaving no usable config.

How to fix it

Provide a kubeconfig before kubectl runs

Generate or materialize credentials and export KUBECONFIG, then confirm connectivity.

aws eks update-kubeconfig --name my-cluster --region us-east-1
export KUBECONFIG="$HOME/.kube/config"
kubectl config current-context && kubectl cluster-info

Assert config exists early

1. Fail fast if kubectl config current-context returns nothing.
2. Echo the resolved KUBECONFIG path and confirm the file is non-empty.
3. Make sure the credential step ran before any kubectl/Helm call.

How to prevent it

• Generate the kubeconfig and export KUBECONFIG as the first cluster step.
• Assert kubectl config current-context succeeds before deploying.
• Fail the job if credential generation did not write a usable config.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation