Helm "UPGRADE FAILED: post-upgrade hooks failed" in CI

By Kaveh Alemi·Latchkey

A resource annotated as a post-upgrade hook (commonly a migration Job) failed or did not complete in time. Helm waits for hook success, then fails the upgrade and reports which hook did not finish.

What this error means

helm upgrade fails with "Error: UPGRADE FAILED: post-upgrade hooks failed: ... job failed: BackoffLimitExceeded" or a timeout on the hook resource.

Error: UPGRADE FAILED: post-upgrade hooks failed: warning: Hook post-upgrade
my-app/templates/migrate-job.yaml failed: job failed: BackoffLimitExceeded

Common causes

The hook Job itself errored

The migration or setup command in the hook Job exited non-zero, hit its backoffLimit, and Helm reported the hook as failed.

The hook did not finish before the timeout

A slow hook that exceeds --timeout is treated as failed even if it would eventually succeed.

How to fix it

Read the hook Job logs

1. Find the hook Job and its pod in the release namespace.
2. Read the pod logs to see the real command failure.
3. Fix the underlying command (migration, credentials, connectivity), then re-run.

kubectl get jobs -n prod
kubectl logs job/my-app-migrate -n prod

Raise the timeout for slow hooks

If the hook is legitimately slow, increase the upgrade timeout so it has room to complete.

helm upgrade --install my-app ./chart -n prod --timeout 10m

How to prevent it

• Make hook commands idempotent so retries are safe.
• Set a realistic --timeout for migration and setup hooks.
• Add hook-delete-policy so old hook Jobs are cleaned up between runs.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation