# Helm "Kubernetes cluster unreachable" in CI

> Fix Helm "Error: INSTALLATION FAILED: Kubernetes cluster unreachable" in CI - Helm has no working kubeconfig or cannot reach the API server from the runner.

Source: https://latchkey.dev/learn/kubernetes/helm-kubernetes-cluster-unreachable-in-ci  
Updated: 2026-06-30

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.

## 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>
```

> A release stuck `pending-upgrade` blocks every later deploy and is usually left behind by a CI job that was cancelled mid-upgrade. `helm rollback` to the last good revision clears it.

## FAQ

### 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?

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

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

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt