DEV Community: Mark Foster

How to Fix the 10 Most Common YAML Errors

Mark Foster — Mon, 12 Oct 2026 11:01:45 +0000

YAML is easy to read and surprisingly easy to break. Its structure comes from indentation, many characters have special meanings, and a value that looks like a string can quietly become a boolean or a number. The result is a deploy that fails with mapping values are not allowed here, or worse, a config that loads without any error but means something you did not intend.

This guide covers the ten mistakes behind almost every YAML problem: what the error looks like, why it happens and how to fix it.

Quickest fix: paste the file into the YAML Validator. It shows the exact line and column of the error, highlights the line, and warns about values that different parsers read differently.

Error messages below are quoted from two places: DevBrace (the free YAML Validator I built) and PyYAML, the parser behind Ansible and most Python tools. Other parsers word things differently, but the causes are the same.

1. Tabs used for indentation

server:
    port: 8080

The YAML specification forbids tab characters for indentation, full stop. Editors that insert tabs, or copy-paste from a web page, are the usual culprits — and tabs are invisible, so the file looks fine.

DevBrace: Tabs are not allowed as indentation (line 2)
PyYAML: found character '\t' that cannot start any token

Fix: replace tabs with spaces. Set your editor to "insert spaces" for .yaml and .yml files. The YAML Formatter rewrites the whole file with consistent space indentation once it parses.

2. Inconsistent indentation

server:
  host: example.com
   port: 8080

host and port are meant to be siblings, but port has three spaces instead of two. To a YAML parser, a different indent means a different level of nesting, so the line no longer fits anywhere.

DevBrace: Nested mappings are not allowed in compact mappings (line 2)

Fix: keys at the same level must start in exactly the same column. Two spaces per level is the convention for Kubernetes, Docker Compose, GitHub Actions and Ansible. When an error points to a line that looks correct, compare its indentation with the line above it.

3. No space after the colon

name:api
port: 8080

A key and its value are separated by a colon followed by a space. Without the space, name:api is not a key at all. The parser reads it together with the next line as one long key that spans two lines, which is not allowed.

DevBrace: Implicit keys need to be on a single line (line 1)

Fix: write name: api. This is also why URLs work unquoted: in url: https://example.com:8443/api, none of the colons inside the value are followed by a space.

4. A colon followed by a space inside a value

message: Error: disk full

The first : separates the key from the value. The second : makes the parser think the value is itself a key, starting a nested mapping on a single line.

DevBrace: Nested mappings are not allowed in compact mappings (line 1, column 10)
PyYAML: mapping values are not allowed here

Fix: quote the value: message: "Error: disk full". Any value containing : or # (a space followed by a hash, which starts a comment) should be quoted.

5. List items and keys mixed at the same level

items:
  - apple
  banana: 2

A node is either a list (- item) or a mapping (key: value), never both. Here items starts as a list, then a key appears at the same indentation.

DevBrace: All mapping items must start at the same column (line 3)

Fix: decide what the data is. Either make every entry a list item:

items:
  - apple
  - banana: 2

or make items a mapping with named keys. Converting the file with YAML to JSON is the fastest way to see which shape you actually wrote.

6. Unclosed quotes and brackets

title: "Hello world
next: 1

ports: [80, 443
host: example.com

A double-quoted string runs until the next unescaped ", even across lines, and a flow list runs until its ]. One missing character swallows the rest of the file, so the reported line is often far below the real mistake.

DevBrace: Missing closing "quote and Flow sequence in block collection must be sufficiently indented and end with a ]

Fix: close the quote or bracket. If the error line makes no sense, search upwards for the last ", ', [ or { that was opened on the same logical value.

7. Duplicate keys

port: 80
host: example.com
port: 8080

The specification says keys in a mapping must be unique, but parsers disagree on what to do about it. PyYAML silently keeps the last value, while JavaScript's js-yaml and Go's yaml.v3 report an error. That means the same file can load in a Python script and fail in a Node or Go service — or load with a value you did not expect.

DevBrace: Map keys must be unique (line 3)

Fix: remove or rename one of the keys. Duplicates usually appear after merging two versions of a file, so check the diff that introduced them.

8. Undefined aliases — and values starting with `*` or `&`

prod:
  <<: *defaults
  replicas: 3

In YAML, &name defines an anchor and *name refers back to it. An alias must come after its anchor, and the anchor must exist in the same document.

DevBrace: Unknown alias *defaults: no anchor &defaults is defined before it (line 2)
PyYAML: found undefined alias 'defaults'

The same rule catches values that merely look like aliases. pattern: *.log is read as a reference to an anchor named .log, not as a glob.

Fix: define &defaults above the alias, or quote text that starts with * or &: pattern: "*.log".

9. Values starting with a reserved character

email: @jane
template: { name }

Several characters cannot start a plain (unquoted) value: @ and ` are reserved, { and [ start a flow mapping or list, ! starts a tag, | and > start a block scalar, and % starts a directive.

DevBrace: Plain value cannot start with reserved character @ (line 1)

The second line is subtler. { name } is valid YAML, but it is a mapping, not the text { name }. The same thing happens with the double-brace template expressions used by Ansible and Helm: an unquoted value that starts with a brace becomes a nested mapping, and PyYAML fails with found unhashable key.

Fix: quote the value: email: "@jane", template: "{ name }". Quote every template expression that starts a value.

10. Values that silently change type

This one produces no error at all, which is what makes it dangerous.

country: NO
enabled: yes
mode: 0644
version: 1.10
zip: 02134
name:

Value	YAML 1.2 parsers	YAML 1.1 parsers (PyYAML, Ruby)
`NO`	the string `"NO"`	the boolean `false`
`yes`, `on`, `off`	strings	booleans
`0644`	the number 644	the octal number 420
`1.10`	the number 1.1	the number 1.1
`02134`	the number 2134	the octal number 1116
`name:` (nothing)	`null`	`null`

The first row is the famous Norway problem: a list of country codes where Norway turns into false. The version: 1.10 row bites everyone eventually — 1.10 and 1.1 are the same number, so the version you wrote is not the version your program reads.

The YAML Validator flags NO, yes, off and 0644 with a warning and the line number, because the file is valid but means different things to different tools.

Fix: quote anything that must stay text: country: "NO", version: "1.10", zip: "02134". If you generate YAML from JSON, the JSON to YAML converter adds these quotes for you.

A debugging checklist

Validate first. Paste the file into the YAML Validator and go to the reported line.
Look above the reported line. Indentation, unclosed quotes and missing colons are usually caused one or two lines earlier.
Check for tabs. Turn on "show whitespace" in your editor.
Quote suspicious values. Anything with :, #, a leading @, *, &, {, [, or a value like yes, no, on, off, version numbers and leading zeros.
See what the parser sees. Convert to JSON with YAML to JSON: the explicit brackets and quotes make wrong nesting and wrong types obvious.
Normalise the file. Once it is valid, run it through the YAML Formatter so indentation stays consistent for the next person who edits it.

Catching YAML errors before they ship

A validator in the browser is perfect while editing. In a repository, add a check to CI so a broken file never reaches production:

# Syntax check with Python (PyYAML)
python -c 'import sys, yaml; [list(yaml.safe_load_all(open(f))) for f in sys.argv[1:]]' config/*.yaml

# Style and syntax with yamllint
yamllint -d '{extends: default, rules: {truthy: {check-keys: false}}}' .

yamllint's truthy rule catches the Norway problem, its key-duplicates rule catches duplicate keys, and indentation catches the rest.

Most YAML errors take seconds to fix once you know which of these ten you are looking at.

Originally published on DevBrace, where you can also try the YAML Validator used in the examples.

How to Fix the 8 Most Common JSON Errors

Mark Foster — Mon, 05 Oct 2026 10:38:16 +0000

SyntaxError: Unexpected token } in JSON at position 212 is one of the least helpful error messages a developer sees. It tells you that the JSON is broken, but not why, and the position is a character offset you have to count to.

The good news: almost every JSON error comes from the same short list of mistakes. This guide covers the eight you will hit most often, what the error looks like in JavaScript and Python, and how to fix each one.

Quickest fix: paste your JSON into the JSON Validator. It names the mistake in plain English, shows the exact line and column, and highlights the broken line.

Why JSON is so strict

JSON looks like a JavaScript object literal, but it is a much smaller language. The specification (RFC 8259) allows only:

objects {} with double-quoted string keys,
arrays [],
strings in double quotes,
numbers, true, false and null.

That's it. No comments, no trailing commas, no single quotes, no undefined. Being strict is what makes JSON portable — every language parses it the same way — but it means small habits from JavaScript or Python break it.

1. Trailing commas

{
  "name": "Jane",
  "role": "admin",
}

JavaScript, TypeScript and Python all allow a comma after the last item. JSON does not.

JavaScript: Expected double-quoted property name in JSON at position 41 (line 4 column 1) in current Chrome and Node.js; older engines say Unexpected token } in JSON
Python: json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes

Fix: remove the comma after the last property or array item.

2. Single quotes

{ 'name': 'Jane' }

Strings and keys must use double quotes ("). Single quotes are the most common mistake when JSON is typed by hand or copied from Python's print() of a dict.

Fix: replace ' with ". If you are producing JSON from Python, use json.dumps(data) instead of str(data) — str() prints Python syntax, not JSON.

3. Unquoted keys

{ name: "Jane", age: 31 }

Valid JavaScript, invalid JSON. Every key must be a double-quoted string.

Fix: wrap each key in double quotes: { "name": "Jane", "age": 31 }.

4. Missing commas

{
  "name": "Jane"
  "role": "admin"
}

Usually caused by adding a new line to an existing object and forgetting the comma on the line above. The parser reports the error on the second line, which is confusing — the mistake is really at the end of the line before.

Fix: add a comma after "Jane". When an error points to the start of a line, always check the end of the previous line first.

5. Comments

{
  // database settings
  "host": "localhost"
}

JSON has no comment syntax. Some tools accept “JSONC” (JSON with comments) — VS Code's settings.json and tsconfig.json are examples — but a standard parser like JSON.parse will reject it.

Fix: remove the comments. If your config needs comments, consider YAML or TOML instead — see JSON to YAML.

6. Python and JavaScript values that aren't JSON

{ "active": True, "manager": None, "score": NaN, "extra": undefined }

Not JSON	Use instead
`True` / `False` (Python)	`true` / `false`
`None` (Python)	`null`
`undefined` (JavaScript)	`null`, or leave the key out
`NaN`, `Infinity`	`null`, or a string like `"NaN"`

NaN is a sneaky one: Python's json.dumps writes NaN by default, producing output that other parsers (including JavaScript's) reject. Pass allow_nan=False to catch it early.

7. Unescaped characters inside strings

{ "path": "C:\new\folder", "quote": "She said "hi"" }

Inside a JSON string, a backslash starts an escape sequence and a double quote ends the string. So \n becomes a newline, \f a form feed — and "hi" closes the string early.

Fix: escape backslashes as \\ and quotes as \":

{ "path": "C:\\new\\folder", "quote": "She said \"hi\"" }

Literal line breaks and tabs inside a string are also invalid; use \n and \t. The JSON Escape tool converts any text into a correctly escaped JSON string.

8. The response isn't JSON at all

SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

(Older engines: Unexpected token < in JSON at position 0.) If the first character is <, you are not parsing JSON — you are parsing an HTML page. Typical causes:

the URL is wrong and the server returned a 404 page,
your session expired and you were redirected to a login page,
the server crashed and returned an HTML error page.

Fix: log the raw response before parsing it, and check the status code and Content-Type header:

const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const type = res.headers.get('content-type') ?? '';
if (!type.includes('application/json')) {
  throw new Error(`Expected JSON, got ${type}: ${(await res.text()).slice(0, 200)}`);
}
const data = await res.json();

A similar case is Unexpected end of JSON input, which means the text was empty or cut off — often an empty response body from a 204 No Content or a request that timed out.

Errors that aren't syntax errors

Some JSON parses fine but still causes bugs:

Duplicate keys: {"role": "user", "role": "admin"} is accepted by most parsers, which silently keep the last value.
Big numbers: integers above 9,007,199,254,740,991 (2⁵³ − 1) lose precision in JavaScript. 1234567890123456789 becomes 1234567890123456800 after JSON.parse. Send large IDs as strings.

The JSON Validator warns about both, even when the syntax is valid.

A debugging checklist

Validate the text and go to the reported line.
If the error is at the start of a line, check the end of the previous line (missing comma).
If the error mentions < or <!DOCTYPE, you received HTML — check the request, not the JSON.
Search for ', //, True, None, NaN and undefined.
Once it parses, format it so the structure is easy to review.

Most JSON errors take seconds to fix once you know which of these eight you are looking at.

Originally published at devbrace.com. DevBrace is a set of free developer tools that run entirely in your browser.

DEV Community: Mark Foster

How to Fix the 10 Most Common YAML Errors

1. Tabs used for indentation

2. Inconsistent indentation

3. No space after the colon

4. A colon followed by a space inside a value

5. List items and keys mixed at the same level

6. Unclosed quotes and brackets

7. Duplicate keys

8. Undefined aliases — and values starting with * or &

9. Values starting with a reserved character

10. Values that silently change type

A debugging checklist

Catching YAML errors before they ship

How to Fix the 8 Most Common JSON Errors

Why JSON is so strict

1. Trailing commas

2. Single quotes

3. Unquoted keys

4. Missing commas

5. Comments

6. Python and JavaScript values that aren't JSON

7. Unescaped characters inside strings

8. The response isn't JSON at all

Errors that aren't syntax errors

A debugging checklist

8. Undefined aliases — and values starting with `*` or `&`