How to fix UPGRADE FAILED in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 161 views

A Helm upgrade operation failed, leaving the release in a failed state. The application may be partially updated.

Quick fix

Fixes UPGRADE FAILED

helm upgrade RELEASE CHART -n NAMESPACE
  1. Check upgrade error details
  2. Verify chart values and syntax
  3. Check cluster resources
  4. Rollback the failed upgrade
kubernetes — error
helm upgrade RELEASE CHART -n NAMESPACE
UPGRADE FAILED

What this error means

When helm upgrade fails (e.g., validation error, image pull failure), the release enters a FAILED state. This is different from rolling back automatically—Helm stops the upgrade and leaves resources in an inconsistent state. You must either fix and retry the upgrade or explicitly rollback.

Typical symptoms

  • helm upgrade returns non-zero exit code
  • helm status shows "FAILED" status
  • Partial changes applied to cluster
  • Pods may be in various states
  • Next helm upgrade also fails
  • Release cannot be deleted until fixed

Common causes

  1. Invalid Helm chart values or syntax errors
  2. Container image cannot be pulled
  3. Insufficient resources (CPU, memory, disk)
  4. Image registry authentication failure
  5. PVC cannot be created or resized
  6. Webhook validation rejection

How to fix "UPGRADE FAILED"

1Check upgrade error details

View the full error:

bash
helm upgrade RELEASE CHART -n NAMESPACE

Read the error message for the root cause.

2Verify chart values and syntax

Test the chart locally:

bash
helm template RELEASE CHART -n NAMESPACE -f values.yaml
helm lint CHART

Fix any syntax errors.

3Check cluster resources

Verify nodes have sufficient resources:

bash
kubectl top nodes
kubectl describe nodes | grep -A5 "Allocatable"
4Rollback the failed upgrade

Revert to the last working version:

bash
helm rollback RELEASE -n NAMESPACE

# Or rollback to specific revision
helm rollback RELEASE 2 -n NAMESPACE
5Fix issues and retry upgrade

After fixing the underlying issue:

bash
helm upgrade RELEASE CHART -n NAMESPACE -f fixed-values.yaml

Advanced notes

Use helm upgrade --dry-run first to validate changes without applying them. Implement pre-upgrade checks (Helm hooks) to validate readiness. For production, use --wait flag to ensure resources are ready before considering upgrade complete. Monitor release status with helm status RELEASE --wait. Document rollback procedures in your runbook.

Frequently asked questions

What does "UPGRADE FAILED" mean?
, validation error, image pull failure), the release enters a FAILED state. This is different from rolling back automatically—Helm stops the upgrade and leaves resources in an inconsistent state. You must either fix and retry the upgrade or explicitly rollback.
How do I fix "UPGRADE FAILED"?
A Helm upgrade operation failed, leaving the release in a failed state. The application may be partially updated.
What causes "UPGRADE FAILED"?
Invalid Helm chart values or syntax errors Container image cannot be pulled Insufficient resources (CPU, memory, disk)
Is the "UPGRADE FAILED" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading