Helm "Kubernetes cluster unreachable" in CI

By Kaveh Alemi·Latchkey

Helm needs a kubeconfig and a reachable API server. In CI this fails when no kubeconfig is configured, the context is wrong, or the runner cannot reach the cluster endpoint.

What this error means

helm install/upgrade/list fails with "Error: INSTALLATION FAILED: Kubernetes cluster unreachable: Get "https://...:6443/version": dial tcp ...: connect: connection refused" or "the server has asked for the client to provide credentials".

Error: INSTALLATION FAILED: Kubernetes cluster unreachable: Get
"https://127.0.0.1:6443/version": dial tcp 127.0.0.1:6443: connect: connection refused

Common causes

No kubeconfig set in the job

The deploy step has no KUBECONFIG, or the cluster credentials were never written, so Helm falls back to a default that points nowhere.

Wrong context or unreachable endpoint

The selected context points at a cluster the runner cannot reach (private endpoint, missing VPN, expired token).

How to fix it

Configure cluster credentials before Helm

1. Write or fetch the kubeconfig (cloud auth action or a secret).
2. Confirm connectivity with kubectl cluster-info before running Helm.
3. Re-run the deploy.

aws eks update-kubeconfig --name prod-cluster --region us-east-1
kubectl cluster-info
helm upgrade --install my-app ./chart -n prod

Point Helm at the right kubeconfig/context

Set KUBECONFIG and select the intended context explicitly so Helm targets the correct cluster.

env:
  KUBECONFIG: ${{ github.workspace }}/kubeconfig
run: helm upgrade --install my-app ./chart --kube-context prod -n prod

How to prevent it

• Authenticate to the cluster and verify with kubectl cluster-info before Helm steps.
• Set KUBECONFIG/--kube-context explicitly in deploy jobs.
• Ensure the runner has network access to private API endpoints.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation