12 Helm Chart Mistakes and How to Fix Them

12 Helm chart mistakes by symptom, cause and fix: versioning, secrets, schema, nindent, quoting, CRDs, drift, Helm 4 flags and stuck releases.

Dec 29, 2025 - 12:24
Nov 10, 2026 - 06:28
 0  80
12 Helm Chart Mistakes and How to Fix Them

The Helm chart mistakes that cause the most failed releases are forgetting to bump the chart version, committing secrets in values files, skipping a values schema, using template instead of include with nindent, leaving values unquoted, hardcoding names and namespaces, unpinned dependencies, managing CRDs in templates, changing resources outside Helm, weak failure handling, no linting or tests, and deleting release records to fix stuck upgrades.

This guide is organised around failures: for each mistake you get the symptom you will actually see, why it happens and the fix. If you want the positive checklist instead, read 10 Helm best practices for smooth Kubernetes deployments; for complete working charts, see 10 Helm chart examples. Flags and behaviour were checked against helm.sh for Helm 4 (latest listed release 4.3.1) in November 2026, with notes where Helm 3 differs.

Key takeaways

  • Helm 4 renamed --atomic to --rollback-on-failure and --force to --force-replace. The old flags still work but print deprecation warnings.
  • Helm 4 uses server-side apply for new releases. Upgrades keep the apply method the release started with.
  • A values.schema.json file is validated on install, upgrade, lint and template, which catches typos that Helm otherwise ignores.
  • CRDs in the crds/ directory are installed but never upgraded or deleted by Helm. Plan a separate path for CRD changes.
  • Run helm lint, helm template and a schema validator such as kubeconform in CI before any chart reaches a cluster.
  • Never fix a stuck release by deleting Helm's release Secrets unless you understand the consequences; use helm history and helm rollback first.

Symptom finder

What you seeLikely mistakeSection
Upgrade "succeeds" but nothing changes, or the repo serves an old chartChart version not bumped1
Passwords visible in Git history or helm get valuesSecrets in values files2
A setting has no effect and no error appearsTypo in a value key, no schema3
error converting YAML to JSON, wrong indentationtemplate instead of include plus nindent4
Version 1.10 becomes 1.1, "yes" becomes trueUnquoted values5
Second install in the same cluster fails with "already exists"Hardcoded names or namespaces6
Builds differ between machinesUnpinned dependencies, no Chart.lock7
New CRD fields never appear after upgradeCRD lifecycle misunderstood8
Upgrade reverts a manual fix, or conflicts on fieldsChanges made outside Helm9
Broken release left half-appliedNo wait or rollback on failure10
Errors found only in productionNo lint, render or tests in CI11
another operation (install/upgrade/rollback) is in progressStuck pending release12

1. Not bumping the chart version (or confusing it with appVersion)

Symptom: you change a template, package the chart and push it, but clusters keep getting the old behaviour, or your chart repository rejects the upload as a duplicate.

Cause: chart repositories and caches key on the chart version in Chart.yaml. The Helm charts documentation says version should follow SemVer 2, while appVersion is informational: it records the application version and does not affect chart version calculations. Bumping only appVersion, or nothing at all, leaves two different charts with the same identity.

Fix: bump version on every chart change, using SemVer meaning (patch for fixes, minor for new optional values, major for breaking changes to values). Update appVersion when the default image changes. Enforce it in CI: fail the pipeline if templates changed but version did not.

apiVersion: v2
name: checkout
version: 1.4.1        # chart version: bump on every chart change
appVersion: "2.8.0"   # application version, informational

2. Putting secrets in values.yaml

Symptom: database passwords appear in Git, in CI logs, and in the output of helm get values.

Cause: values files are plain text, and Helm stores the rendered release (including values) in the cluster, by default as a Secret in the release namespace. Anyone with read access to those Secrets, or to the Git repository, can read the password.

Fix: keep secret values out of the chart repository. Options include encrypting values files with SOPS (often through the helm-secrets plugin), referencing secrets that already exist in the cluster with existingSecret-style values, or syncing from a secret manager with the External Secrets Operator. In the chart, make the secret name configurable rather than the secret content:

# values.yaml
database:
  existingSecret: checkout-db
  passwordKey: password

More approaches are compared in 10 tools to manage Kubernetes secrets safely.

3. Shipping a chart without values.schema.json

Symptom: someone sets replicaCount: 5 as replicacount: 5, or passes a string where a number is expected, and the release installs with the default instead. No error appears.

Cause: Helm merges whatever values you give it. Unknown keys are ignored by templates that never read them.

Fix: add a JSON Schema file named values.schema.json to the chart root. Helm validates values against it during helm install, helm upgrade, helm lint and helm template, as stated in the charts documentation.

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image"],
  "additionalProperties": false,
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      }
    }
  }
}

additionalProperties: false at the top level is what catches typos. Be careful using it on charts that are used as subcharts, because parent charts pass a global key down; include global in the allowed properties if you rely on it. The --skip-schema-validation flag exists, but treat it as an emergency escape hatch, not a default.

4. Using template instead of include, and fighting indentation

Symptom: error converting YAML to JSON, labels landing at the wrong indentation, or manifests that render but put fields in the wrong place.

Cause: template is an action, so its output is inserted inline and cannot be piped to functions. The named templates guide explains that this is why include is preferred: it returns a string you can pipe to nindent to control indentation.

# wrong: output is inserted inline at whatever column it lands
metadata:
  labels:
{{ template "checkout.labels" . }}

# right: include + nindent sets indentation explicitly
metadata:
  labels:
    {{- include "checkout.labels" . | nindent 4 }}
spec:
  template:
    spec:
      containers:
      - name: app
        resources:
          {{- toYaml .Values.resources | nindent 10 }}

The leading {{- trims the whitespace and newline before the action, and nindent adds a newline plus the right number of spaces. When in doubt, render the chart with helm template and read the output; indentation bugs are obvious in rendered YAML and invisible in templates.

5. Leaving values unquoted

Symptom: an image tag of 1.10 deploys as 1.1, an environment variable meant to be the string "yes" becomes a boolean, or a large number turns into scientific notation.

Cause: YAML parses unquoted scalars into types. Helm's values best practices recommend quoting all strings and note that large integers can be converted to scientific notation.

Fix: quote strings in values.yaml, and quote them again in templates where Kubernetes expects a string, such as environment variable values and annotations:

image:
  tag: "1.10"
env:
  FEATURE_FLAG: "yes"

# in the template
- name: FEATURE_FLAG
  value: {{ .Values.env.FEATURE_FLAG | quote }}

Be careful with --set on the command line too: --set image.tag=1.10 is parsed as a number. Use --set-string for values that must stay strings.

6. Hardcoding names and namespaces

Symptom: installing the chart a second time, for example for a staging and a preview environment in one cluster, fails because a resource "already exists". Or resources appear in a namespace the user did not choose.

Cause: templates use fixed names like name: checkout or set metadata.namespace directly.

Fix: derive names from the release using the helpers generated by helm create, which truncate to 63 characters because many Kubernetes name fields are limited to that length. Omit metadata.namespace or set it to {{ .Release.Namespace }}, so helm install -n controls placement. Use the standard app.kubernetes.io/name and app.kubernetes.io/instance labels so selectors stay unique per release.

metadata:
  name: {{ include "checkout.fullname" . }}
  namespace: {{ .Release.Namespace }}
  labels:
    {{- include "checkout.labels" . | nindent 4 }}

Remember that a Deployment's spec.selector is immutable. Changing selector labels between chart versions forces you to delete and recreate the Deployment, so get them right early.

7. Unpinned dependencies and a missing Chart.lock

Symptom: the same chart version renders differently on a laptop and in CI, or a subchart upgrade arrives without anyone choosing it.

Cause: dependency versions in Chart.yaml use wide ranges such as ">=12.0.0", and the resolved versions are not recorded.

Fix: use a bounded range (for example ~12.5.0 for patch updates only), run helm dependency update to resolve it, and commit the generated Chart.lock. In CI, run helm dependency build, which installs exactly what the lock file lists. The helm dependency command reference describes both commands.

dependencies:
- name: postgresql
  version: "~16.4.0"
  repository: "oci://registry-1.docker.io/bitnamicharts"
  condition: postgresql.enabled

Check the chart repository and licence terms of any third-party dependency before you pin it, since publishers change distribution models over time.

8. Managing CRDs the wrong way

Symptom: you ship a new operator version with new CRD fields, upgrade the release, and the cluster still has the old CRD. Or uninstalling a chart unexpectedly deletes every custom resource of that type.

Cause: Helm's CRD guidance says CRDs placed in the crds/ directory are installed but are not templated, and there is no support for upgrading or deleting them with Helm. If a CRD already exists, Helm skips it with a warning. Putting CRDs in templates/ instead means they are upgraded, but also deleted on helm uninstall, which deletes all custom resources of that kind.

Fix: keep CRDs in crds/ for first install, and apply CRD upgrades through a separate, deliberate step (a dedicated CRD chart, kubectl apply --server-side in the pipeline, or the operator's own upgrade mechanism). Document the process in the chart README. Use --skip-crds when CRDs are managed elsewhere.

9. Changing Helm-managed resources outside Helm

Symptom: someone fixed an incident with kubectl edit or kubectl scale, and the next helm upgrade silently reverts it, or reports field ownership conflicts.

Cause: Helm compares the chart against its record of the last release and the live object. Manual edits are drift. Helm 4 defaults to server-side apply for new releases, according to the Helm 4 overview, so field ownership is tracked by the API server and conflicts with other field managers become visible. Upgrades and rollbacks keep the apply method a release already used, so releases created with Helm 3 stay on client-side apply unless you pass --server-side.

Fix: make every lasting change through values and a new release. If an autoscaler owns replicas, do not render replicas in the Deployment when HPA is enabled:

spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}

Use helm diff (a popular plugin) or helm upgrade --dry-run before applying, so you see what will change. A GitOps controller such as Argo CD or Flux makes drift visible continuously; see top GitOps tools for Kubernetes automation.

10. No wait and no rollback on failure

Symptom: helm upgrade reports success, but pods are crash-looping. Or a failed upgrade leaves some resources on the new version and some on the old one.

Cause: without waiting, Helm considers a release successful once the API server accepts the manifests, whether or not the pods ever become ready.

Fix: wait for resources and roll back automatically when they fail:

# Helm 4
helm upgrade --install checkout ./checkout -n shop \
  --wait --timeout 10m --rollback-on-failure

# Helm 3 equivalent
helm upgrade --install checkout ./checkout -n shop \
  --wait --timeout 10m --atomic

In Helm 4, --atomic still works but prints a deprecation warning pointing to --rollback-on-failure. Waiting only works if readiness means something, so the chart must define readiness probes; see how liveness and readiness probes improve reliability. Set a timeout longer than a normal rollout, including image pulls and slow-starting apps.

11. No linting, rendering or tests in CI

Symptom: template errors, invalid API versions and missing required fields show up only when a release fails in a real cluster.

Fix: run a short pipeline on every chart change:

helm lint ./checkout --strict -f values-prod.yaml
helm template checkout ./checkout -f values-prod.yaml > rendered.yaml
kubeconform -strict -summary rendered.yaml
helm install checkout ./checkout -n ci --create-namespace --wait
helm test checkout -n ci

helm lint catches chart structure and template problems. helm template renders locally so you can validate the output against Kubernetes schemas with a tool such as kubeconform, which catches removed API versions before the cluster does. helm test runs the test pods defined in templates/tests/ against an installed release. Lint with each values file you ship (dev, staging, prod), because different values switch on different template branches. Pipelines for this are in 14 CI/CD solutions for Kubernetes workloads.

12. Deleting release records to "fix" a stuck release

Symptom: Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress, and helm list -a shows the release as pending-upgrade or pending-install.

Cause: a previous Helm process was interrupted (a CI job timed out or was cancelled) before it could record the final status.

Fix: first confirm that no other Helm process is still running against the release. Then look at history and roll back to the last good revision:

helm history checkout -n shop
helm rollback checkout 7 -n shop --wait

Deleting the release's storage Secrets (the sh.helm.release.v1.* objects) is a last resort. It erases Helm's memory of the release, and a later upgrade may try to recreate resources that already exist. If you do it, back up the Secret first and understand which revision you are removing. To prevent the problem, give CI jobs a timeout longer than the Helm --timeout, so Helm finishes before the job is killed.

Pre-release checklist

  1. Chart version bumped; appVersion matches the default image.
  2. No secrets in any values file in Git.
  3. values.schema.json present and passing.
  4. Names derived from the release; no hardcoded namespace.
  5. Chart.lock committed and dependencies within bounded ranges.
  6. CRD upgrade path documented.
  7. helm lint --strict, render and schema validation pass for every values file.
  8. Deployment uses --wait, a realistic --timeout and rollback on failure.

Helm, chart authoring and Kubernetes release workflows are part of our CKAD training, available in the Kharadi, Pune classroom and live online. To test your knowledge, try 40 Helm scenario interview questions.

FAQ

What is the difference between version and appVersion in Chart.yaml?

version is the chart's own SemVer version and must change whenever the chart changes. appVersion records the application version the chart deploys by default. It is informational and does not affect chart versioning.

Is --atomic removed in Helm 4?

No. Helm 4 renamed it to --rollback-on-failure. The old --atomic flag still works but prints a deprecation warning, so update scripts when you move to Helm 4.

Why are my CRDs not updated by helm upgrade?

Helm installs CRDs from the crds/ directory but does not upgrade or delete them. Apply CRD changes through a separate step, such as a dedicated CRD chart or kubectl apply in your pipeline.

How do I stop typos in values from being ignored?

Add a values.schema.json file. Helm validates values against it on install, upgrade, lint and template. Setting additionalProperties to false makes unknown keys fail validation.

Should I store secrets in values.yaml?

No. Values are plain text and end up in Helm's release records. Use encrypted values with SOPS, reference existing Kubernetes Secrets, or sync from a secret manager with External Secrets Operator.

How do I fix "another operation is in progress"?

Make sure no Helm process is still running, then use helm history and helm rollback to a known good revision. Deleting release Secrets is a last resort that removes Helm's record of the release.

Does Helm 4 change how resources are applied?

Yes. Helm 4 uses server-side apply for new releases. Existing releases keep the apply method they were created with, so Helm 3 releases continue with client-side apply unless you pass --server-side.

Which commands should run in CI for a Helm chart?

At minimum helm lint --strict and helm template with each values file, then a schema validator such as kubeconform on the rendered output. Add an install plus helm test in a disposable namespace if you can.

What's Your Reaction?

Like Like 0
Dislike Dislike 0
Love Love 0
Funny Funny 0
Angry Angry 0
Sad Sad 0
Wow Wow 0
Mridul I am a passionate technology enthusiast with a strong focus on DevOps, Cloud Computing, and Cybersecurity. Through my blogs at DevOps Training Institute, I aim to simplify complex concepts and share practical insights for learners and professionals. My goal is to empower readers with knowledge, hands-on tips, and industry best practices to stay ahead in the ever-evolving world of DevOps.