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.
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
--atomicto--rollback-on-failureand--forceto--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.jsonfile 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 templateand 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 historyandhelm rollbackfirst.
Symptom finder
| What you see | Likely mistake | Section |
|---|---|---|
| Upgrade "succeeds" but nothing changes, or the repo serves an old chart | Chart version not bumped | 1 |
Passwords visible in Git history or helm get values | Secrets in values files | 2 |
| A setting has no effect and no error appears | Typo in a value key, no schema | 3 |
error converting YAML to JSON, wrong indentation | template instead of include plus nindent | 4 |
Version 1.10 becomes 1.1, "yes" becomes true | Unquoted values | 5 |
| Second install in the same cluster fails with "already exists" | Hardcoded names or namespaces | 6 |
| Builds differ between machines | Unpinned dependencies, no Chart.lock | 7 |
| New CRD fields never appear after upgrade | CRD lifecycle misunderstood | 8 |
| Upgrade reverts a manual fix, or conflicts on fields | Changes made outside Helm | 9 |
| Broken release left half-applied | No wait or rollback on failure | 10 |
| Errors found only in production | No lint, render or tests in CI | 11 |
another operation (install/upgrade/rollback) is in progress | Stuck pending release | 12 |
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
- Chart
versionbumped;appVersionmatches the default image. - No secrets in any values file in Git.
values.schema.jsonpresent and passing.- Names derived from the release; no hardcoded namespace.
Chart.lockcommitted and dependencies within bounded ranges.- CRD upgrade path documented.
helm lint --strict, render and schema validation pass for every values file.- Deployment uses
--wait, a realistic--timeoutand 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
0
Dislike
0
Love
0
Funny
0
Angry
0
Sad
0
Wow
0