How to fix "error converting YAML to JSON" in Kubernetes and Helm

What kubectl and Helm mean by "error converting YAML to JSON", the seven messages behind it, and how to fix each one, with before and after examples.

Troubleshooting By Convert JSON to YAML Team

How to fix "error converting YAML to JSON" in Kubernetes and Helm

Kubernetes speaks JSON internally. When you run kubectl apply -f deployment.yaml or helm install, the YAML is first converted to JSON, and only then sent to the API server. If that conversion fails, the error starts with error converting YAML to JSON, followed by the real problem from the YAML parser:

error: error parsing deployment.yaml: error converting YAML to JSON: yaml: line 12: mapping values are not allowed in this context

So the prefix tells you only where it failed. The part after yaml: tells you why, and the line number tells you where to look. Below are the messages you will meet most often, what causes each, and the fix.

Paste the file into the YAML validator to see the problem line highlighted, with the column, before you run kubectl again.

1. mapping values are not allowed in this context

The most common one. A plain (unquoted) value contains : (colon and space), so the parser thinks a new key starts in the middle of the value. URLs with ports, times and log formats are typical culprits.

# Broken
command: echo started: true

# Fixed
command: 'echo started: true'

It also appears when a key is indented under a line that already has a value:

# Broken: "image" is indented under a scalar
name: web
  image: nginx

# Fixed
name: web
image: nginx

2. found character that cannot start any token

Nearly always a tab character used for indentation. YAML allows only spaces. Some editors insert tabs when you press the Tab key, and they look identical to spaces on screen.

Fix: replace tabs with spaces (two per level is the Kubernetes convention). In VS Code, run “Convert Indentation to Spaces”. The same message appears for a value that starts with a reserved character such as @ or a backtick; quote those values.

3. did not find expected key

The parser was inside a mapping and expected another key: at the same indentation, but found something else. Usually one line is indented by a different number of spaces than its siblings.

# Broken: "ports" has one space too few
spec:
  containers:
    - name: web
      image: nginx
     ports:
        - containerPort: 80

# Fixed
spec:
  containers:
    - name: web
      image: nginx
      ports:
        - containerPort: 80

In Helm charts this message is the classic symptom of a template that renders at the wrong indentation (see the Helm section below).

4. could not find expected ’:’

A line looks like it should be a key but has no colon. Typical causes are a forgotten colon, or a long string that was wrapped onto the next line without a block scalar.

# Broken
description: This text is long
and continues here

# Fixed: use a block scalar for multi-line text
description: |
  This text is long
  and continues here

5. did not find expected ’-’ indicator

A list item is out of line with the items before it. Every - in one list must start at the same column.

6. block sequence entries are not allowed in this context

A list starts on the same line as a key that already has a value, or directly after a mapping key without a line break.

# Broken
args: - --port=80

# Fixed
args:
  - --port=80

7. The YAML parses, but the API server rejects the type

Once the conversion succeeds, Kubernetes decodes the JSON into typed Go structs. A quoted number where an integer is expected, or an unquoted number where a string is expected, fails at this second step:

json: cannot unmarshal string into Go struct field DeploymentSpec.spec.replicas of type int32

replicas: "3" must be replicas: 3. The reverse happens with environment variables: value: 8080 must be value: "8080", because env values are strings. Our Kubernetes converter quotes strings that look like numbers or booleans for exactly this reason.

Helm: errors in rendered templates

With Helm, the line number refers to the rendered manifest, not to your template file:

Error: YAML parse error on web/templates/deployment.yaml: error converting YAML to JSON: yaml: line 31: did not find expected key

Render the chart to see the actual YAML that failed, then count to that line:

helm template web ./chart --debug > rendered.yaml

The usual cause is inserting a multi-line block with the wrong indentation. Use nindent with the indentation of the place you insert into, and toYaml for structured values:

# Broken: the inserted block starts at column 0
      resources:
{{ toYaml .Values.resources }}

# Fixed
      resources:
        {{- toYaml .Values.resources | nindent 8 }}

Values that must stay strings should go through quote, for example value: {{ .Values.port | quote }}.

A quick checklist

  1. Read the part after yaml:; the prefix is the same for every failure.
  2. Go to the reported line, and also check the line just above it: the parser often notices a problem one line late.
  3. Look for tabs, uneven indentation and unquoted values containing : or #.
  4. For Helm, debug the rendered output with helm template --debug, not the template.
  5. If the YAML parses but the server rejects it, check value types: numbers versus quoted strings.

You can check any of this without a cluster: paste the manifest into the YAML validator, or convert it with the YAML to JSON converter to see exactly the JSON that kubectl would send.

← Blog