Helm "cannot re-use a name that is still in use" vs "no deployed releases" in CI

By Kaveh Alemi·Latchkey

A previous Helm operation left the release in a failed, pending-install, or uninstalling state, and a fresh helm install refuses to proceed over it. The new install is not the problem - leftover release state from the prior run is blocking it.

What this error means

helm install fails referencing an existing release that did not finish cleanly - a release named <x> is in a failed state or it is mid-uninstalling. Re-running the same install keeps failing until the stale release record is cleared.

helm output

Error: INSTALLATION FAILED: a release named api is in a failed state; run
`helm status api` to check or `helm uninstall api` to remove it

Common causes

Prior install/upgrade failed mid-flight

An earlier run errored after creating the release record but before completing, leaving it in failed/pending-install. Helm will not silently install over that state.

A previous uninstall did not complete

An uninstall that was interrupted leaves the release uninstalling, so a new install collides with the half-removed record.

How to fix it

Inspect status, then clean up the stuck release

Check the release state and remove or roll back the stale record before reinstalling.

Terminal

helm status api -n prod
helm history api -n prod
helm uninstall api -n prod        # if it should be removed
# or, for first-install failures with --replace / reinstall
helm install api ./chart -n prod

Make CI deploys idempotent

Prefer helm upgrade --install so a clean prior release is upgraded rather than re-installed.
For a stuck pending-install on first deploy, uninstall the partial release before retrying.
Use --atomic so a failed install cleans up after itself and does not leave a blocking record.

Terminal

helm upgrade --install api ./chart -n prod --atomic --timeout 5m

How to prevent it

Use helm upgrade --install --atomic so failures self-clean and reruns are idempotent.
Check helm status and clean up stale releases in CI before reinstalling.
Do not interrupt Helm operations mid-flight in pipelines.

Frequently asked questions

What causes "Helm release in failed state"?

An earlier run errored after creating the release record but before completing, leaving it in failed/pending-install. Helm will not silently install over that state.

How do I fix Helm release in failed state?