Helm "failed post-install hook" in CI - Fix it

Helm hooks run as Jobs/Pods at lifecycle points. A failed post-install/post-upgrade hook means that Job did not finish successfully (it errored, crashed, or timed out), so Helm marks the whole release failed.

What this error means

helm upgrade fails with Error: failed post-install: warning: Hook post-install <name> failed: job failed: BackoffLimitExceeded (or a timeout). The hook Job shows failed pods.

helm

Error: UPGRADE FAILED: failed post-install: warning: Hook post-install
api/templates/migrate-job.yaml failed: job failed: BackoffLimitExceeded

Common causes

Hook Job logic failed

A migration/seed/init Job inside the hook errored (bad command, DB unreachable, missing secret) and exhausted its backoffLimit.

Hook timed out or dependency not ready

The hook ran before its dependency (DB, service) was reachable, or the hook deletion policy left a stale Job.

How to fix it

Read the hook Job logs

The hook Job pod logs carry the real failure.

Terminal

kubectl get jobs -l app.kubernetes.io/instance=api
kubectl logs job/<hook-job>
kubectl describe job <hook-job>

Fix the hook and re-run

Resolve the Job error (command, credentials, dependency reachability).
Set a sensible hook-delete-policy (e.g. before-hook-creation) so stale Jobs do not block re-runs.
Re-run; if the failure was a transient dependency hiccup, a retry may clear it.

How to prevent it

Make hook Jobs idempotent and dependency-aware (wait/retry inside the Job).
Use hook-delete-policy to avoid stale hook Jobs.
Keep migrations safe to re-run.