How to Fix YAML to JSON Conversion Errors — 8 Common Problems Solved

YAML to JSON conversion errors have eight common root causes. Once you know which error message maps to which problem, most fixes take under 30 seconds. The most frequent issues are tabs instead of spaces for indentation, unquoted colons in string values, and invisible control characters pasted from web pages or emails.

This guide maps each error message to its cause and shows the exact fix — both for the free browser converter and for programmatic conversion in Python and Node.js.

Error: "bad indentation" or "did not find expected key"

What it means: The YAML parser found content at an unexpected indentation level. Either a nested item is indented at the wrong level, or a mapping key appears where a value is expected.

Most common cause: A string value contains a colon without quoting. YAML interprets the colon as a key-value separator:

# Broken — YAML reads "http://example.com" as a key
url: http://example.com

# Fixed — quote the value
url: "http://example.com"

Second common cause: Inconsistent indentation. A child block is indented at a different depth than sibling blocks:

# Broken
parent:
  child1: value1
    child2: value2  # wrong — should be same level as child1

# Fixed
parent:
  child1: value1
  child2: value2

Count spaces carefully. YAML uses relative indentation — there is no required number of spaces, but all siblings must use the same count.

Error: "found character that cannot start any token" — Tab Characters

What it means: YAML does not allow tab characters (\t) for indentation. Tabs look identical to spaces visually but cause this error.

How it happens: You wrote the YAML in an editor set to "insert tab" mode, or copied YAML from a web page that used tab characters in <pre> blocks.

How to fix:

In VS Code: Edit > Replace (Ctrl+H), enable regex mode, find \t, replace with two spaces. Click Replace All.

In Notepad++: Search menu > Replace (Ctrl+H), find \t in Extended mode, replace with two spaces.

Using the command line:

# On Linux/Mac with sed
sed -i 's/\t/  /g' input.yaml

# On Windows PowerShell
(Get-Content input.yaml) -replace "\t","  " | Set-Content input.yaml

Error: "control characters are not allowed" or "yaml control characters"

What it means: The YAML file contains non-printable characters (ASCII code 0-31 or 127) outside of quoted strings. Common culprits: null bytes, form feeds, carriage returns (\r), or Unicode direction markers.

How it happens: You copied YAML from a PDF, Word document, or web page that embeds invisible formatting characters. Some email clients also insert zero-width spaces.

How to fix:

The cleanest approach: open the YAML file in a hex editor or run this command to show non-printable characters:

cat -A input.yaml | grep -n '[^[:print:]\t\n]'

On Windows with PowerShell:

[System.IO.File]::ReadAllBytes('input.yaml') | Where-Object {$_ -lt 32 -and $_ -ne 9 -and $_ -ne 10 -and $_ -ne 13}

The simplest fix: retype the affected lines from scratch rather than copying from the original source. Once the invisible characters are removed, conversion will succeed.

Sell Custom Apparel — We Handle Printing & Free Shipping

Error: "mapping values are not allowed here"

What it means: A colon appears where YAML does not expect a key-value separator — usually inside a flow sequence ([]) or after a list item that was not meant to be a mapping.

Common examples:

# Broken — "2026-04-14T10:00:00" looks like a key to YAML
timestamp: 2026-04-14T10:00:00

# Fixed — quote the timestamp
timestamp: "2026-04-14T10:00:00"

# Broken — URL in a list without quotes
urls:
  - https://example.com/api

# Fixed — quote URLs in lists
urls:
  - "https://example.com/api"

Any string value that contains : followed by a space should be quoted. This includes timestamps, URLs, host:port patterns, and labels like "Status: Active".

Error: "found unexpected end of stream"

What it means: The YAML ends before the parser expected. Usually a key with no value, or an opening structure (list item, nested block) with no content.

# Broken — key with no value
database:
  host:    # empty value causes this error

# Fixed — empty string value
database:
  host: ""    # or use null, or ~ for null

# Also broken — trailing colon with nothing after it
config:

In Helm templates, this error sometimes appears when a template variable is undefined and produces an empty output. The fix is to add a default value: {{ .Values.host | default "localhost" }}.

Check the last few lines of your YAML file — the error typically occurs at the very end of the content.

Helm-Specific YAML to JSON Errors

Helm templates are YAML with additional Go template syntax ({{ }} expressions). If you paste a raw Helm template into a YAML converter, it will fail — the {{ }} syntax is not valid YAML.

To convert a Helm template to JSON, you must first render it:

helm template my-release ./my-chart --values values.yaml > rendered.yaml

Then convert the rendered YAML (which is pure YAML with no {{ }} expressions) to JSON using the browser tool or yq.

The error message for raw Helm templates is usually "found unknown escape character" or "mapping values are not allowed here" — because {{ }} blocks break YAML structure.

Similarly, Jinja2 templates ({{ }} in Ansible) are not valid YAML until rendered. Run ansible-playbook --syntax-check to validate rendered Ansible playbooks.

Frequently Asked Questions

Why does my YAML to JSON conversion keep failing?

The most common causes are: tabs for indentation (use spaces), colon in an unquoted string value (add quotes around the value), invisible control characters pasted from a PDF or web page (retype the affected lines), or a key with no value (add an empty string or null). Paste your YAML into the converter to see the specific error message.

What does "did not find expected key" mean in YAML?

This error usually means YAML found a colon or special character in an unexpected place — most often inside a URL or timestamp that is not quoted. Example: url: http://example.com causes this error. Fix: url: "http://example.com"

What does "control characters are not allowed" mean in YAML?

Your YAML file contains non-printable characters (invisible formatting characters) that YAML forbids outside of quoted strings. This often happens when copying YAML from PDFs, Word documents, or web pages. Retype the affected lines from scratch to remove the invisible characters.

Can I convert YAML to JSON if it has Helm template expressions in it?

No — Helm templates with {{ }} expressions are not valid YAML until rendered. Run helm template first to produce rendered YAML, then convert that output to JSON.