DEV Community

Cover image for Debugging Helm Template Errors: Lessons Learned
Jayesh Shinde
Jayesh Shinde

Posted on

Debugging Helm Template Errors: Lessons Learned

#kubernetes #helm

Today while working with Helm to package my Kubernetes deployments, I hit a couple of tricky but interesting issues. Writing them down so that it may help others facing the same problem.

1. Keys with - in values.yaml

In my values.yaml, I had a key like this:

postgresql-pvc:
  storage: 1Gi
Enter fullscreen mode Exit fullscreen mode

And in my template (postgresql.yaml), I tried to reference it like this:

storage: {{ .Values.postgresql.postgresql-pvc.storage }}
Enter fullscreen mode Exit fullscreen mode

This failed with an error:

[ERROR] templates/: parse error: bad character U+002D '-'
Enter fullscreen mode Exit fullscreen mode

Why?
Helm templates treat the - in postgresql-pvc as a subtraction operator.

Fix:
Wrap the key in quotes and use index notation:

storage: {{ index .Values.postgresql "postgresql-pvc" "storage" }}
Enter fullscreen mode Exit fullscreen mode

This tells Helm clearly that it’s a key lookup, not math.

OR

Better to avoid using "-" in the key simply use like below in values.yaml file

postgresqlPvc:
  storage: 1Gi
Enter fullscreen mode Exit fullscreen mode

and then in helm template

storage: {{ index .Values.postgresql.postgresqlPvc.storage" }}
Enter fullscreen mode Exit fullscreen mode

2. Numbers in values.yaml need quotes

The second issue I faced was with environment variables in a Deployment. My values.yaml had:

postgresql:
  servicePort: 5432
Enter fullscreen mode Exit fullscreen mode

And in the Deployment template:

env:
  - name: POSTGRES_PORT
    value: {{ .Values.postgresql.servicePort }}
Enter fullscreen mode Exit fullscreen mode

This failed with:

cannot unmarshal number into Go struct field EnvVar.spec.template.spec.containers.env.value of type string
Enter fullscreen mode Exit fullscreen mode

Why?
Kubernetes expects environment variable values to always be strings, but Helm rendered it as a number.

Fix:
Wrap the value in quotes:

env:
  - name: POSTGRES_PORT
    value: "{{ .Values.postgresql.servicePort }}"
Enter fullscreen mode Exit fullscreen mode

Now Helm correctly renders it as a string.

Checklist for Debug

Env vars (value: in env) → always string

Labels and annotations → always string

Secrets/ConfigMaps → always string

Ports, replicas, resource requests → can stay as numbers

Check the Kubernetes API spec for the field type (string vs number)

Takeaway

Helm is powerful, but also picky:

  • Keys with - need quotes and index lookup.
  • Numbers used as environment variables should be wrapped in quotes.

Small things, but they save a lot of head-scratching once you know them.

Top comments (0)