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

helm

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

Diagnose it: render the chart before you install it

Most Helm failures are visible in the rendered manifests. Template them locally with the same values CI uses and you will usually see the problem without touching the cluster.

Terminal

# what will actually be applied
helm template <release> <chart> -f values.ci.yaml | head -60

# validate against the live cluster schema without installing
helm install <release> <chart> -f values.ci.yaml --dry-run --debug

# what state is the release actually in?
helm history <release>
helm status <release>

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

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

Terminal

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.

.github/workflows/ci.yml

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

What causes Helm "Kubernetes cluster unreachable" in CI?

There are 2 common causes: no kubeconfig set in the job and wrong context or unreachable endpoint. The deploy step has no KUBECONFIG, or the cluster credentials were never written, so Helm falls back to a default that points nowhere.

How do I fix Helm "Kubernetes cluster unreachable" in CI?

There are 2 fixes depending on which cause you have: configure cluster credentials before helm and point helm at the right kubeconfig/context. Work through them in order, since the first is the most common.

What does Helm "Kubernetes cluster unreachable" in CI actually mean?

How do I stop Helm "Kubernetes cluster unreachable" in CI happening again?

Authenticate to the cluster and verify with kubectl cluster-info before Helm steps. The prevention section lists 3 changes that keep it from recurring.