Helm "pre-install/pre-upgrade hook failed" - Fix Hook Job Failures in CI

Helm runs lifecycle hooks (pre-install, pre-upgrade, post-install, etc.) as Jobs at defined points in a release. If a hook Job fails or times out, Helm aborts the release at that phase - the hook’s pod logs hold the real reason, not the Helm message.

What this error means

helm install/upgrade fails with Error: ... pre-upgrade hooks failed: job failed: BackoffLimitExceeded (or DeadlineExceeded). The release does not complete because the hook Job never succeeded.

helm output

Error: UPGRADE FAILED: pre-upgrade hooks failed: 1 error occurred:
* job migrate-db failed: BackoffLimitExceeded

Common causes

The hook Job exits non-zero

A migration, a setup script, or a validation hook fails (bad command, failing dependency, wrong config), exhausting its backoffLimit - so Helm reports the hook failed.

Hook deletion policy hides the evidence

A hook-delete-policy: hook-succeeded/before-hook-creation can remove the hook Job/pod, making it look like it "vanished" and hiding the logs that explain the failure.

How to fix it

Read the hook Job’s pod logs

The failure is in the hook’s pod. Inspect it before re-running - and keep it around if a delete policy removed it.

Terminal

kubectl get jobs -l app.kubernetes.io/instance=<release>
kubectl logs job/<hook-job> --tail=100
kubectl describe job <hook-job> | sed -n '/Events/,$p'

Fix the hook and control its delete policy

Fix what the hook does (the migration/script error its logs show).
Set helm.sh/hook-delete-policy to keep the Job on failure (e.g. only delete hook-succeeded) so logs survive.
Make hooks idempotent so a retry after a partial run is safe.

How to prevent it

Keep hook Jobs idempotent and well-tested (migrations especially).
Use a hook-delete-policy that preserves failed hook pods for debugging.
Surface hook pod logs in CI so a hook failure is diagnosable.