Introduction

Helm releases are namespace-scoped -- a release installed in one namespace cannot be upgraded from a different namespace. When the --namespace flag is omitted or set to a different namespace than the original install, Helm cannot find the release and either creates a new release in the wrong namespace or fails with a release not found error.

Symptoms

  • helm upgrade fails with release not found despite the release existing in another namespace
  • Two releases with the same name exist in different namespaces
  • helm list does not show the expected release
  • Resources deployed to wrong namespace after install without --namespace
  • Error message: Error: release: not found or cannot re-use a name that is still in use

Common Causes

  • --namespace flag omitted from helm upgrade command
  • Namespace specified in values.yaml but overridden by the default namespace on the CLI
  • Helm 2 to Helm 3 migration changing how namespaces are handled
  • CI/CD pipeline using different namespace for install and upgrade steps
  • HELM_NAMESPACE environment variable not set or different between environments

Step-by-Step Fix

  1. 1.Find the release across all namespaces: Locate the actual release namespace.
  2. 2.```bash
  3. 3.helm list --all --all-namespaces | grep my-release
  4. 4.`
  5. 5.Upgrade with the correct namespace: Use the namespace where the release exists.
  6. 6.```bash
  7. 7.helm upgrade my-release ./chart \
  8. 8.--namespace production \
  9. 9.--reuse-values \
  10. 10.--wait
  11. 11.`
  12. 12.Verify resources are in the correct namespace: Check the deployed resources.
  13. 13.```bash
  14. 14.kubectl get all -n production -l app.kubernetes.io/instance=my-release
  15. 15.`
  16. 16.If the release is in the wrong namespace, migrate it: Move the release to the correct namespace.
  17. 17.```bash
  18. 18.# Export the release
  19. 19.helm get values my-release -n wrong-namespace > values-backup.yaml
  20. 20.# Uninstall from wrong namespace
  21. 21.helm uninstall my-release -n wrong-namespace
  22. 22.# Reinstall in correct namespace
  23. 23.helm install my-release ./chart -n correct-namespace -f values-backup.yaml
  24. 24.`
  25. 25.Add namespace validation to deployment scripts: Prevent future mismatches.
  26. 26.```bash
  27. 27.#!/bin/bash
  28. 28.NAMESPACE="${NAMESPACE:-production}"
  29. 29.helm upgrade my-release ./chart \
  30. 30.--namespace "$NAMESPACE" \
  31. 31.--create-namespace \
  32. 32.--wait --timeout 5m
  33. 33.`

Prevention

  • Always specify --namespace explicitly in all Helm commands, never rely on the default
  • Set KUBECONFIG context with the correct namespace for the target environment
  • Use --create-namespace to ensure the namespace exists before installation
  • Include namespace validation in CI/CD deployment pipelines
  • Document the expected namespace for each Helm release in the deployment runbook
  • Use Helmfile or similar tools that enforce namespace configuration declaratively