The Exact Error
YAMLException: bad indentation of a mapping entry at line 4, column 3
YAMLException: mapping values are not allowed here at line 7, column 10
Error: YAML parse error ā unexpected token ':'
Quick summary: YAML is indentation-sensitive and uses
:as a key-value separator. A:inside an unquoted value, a tab character used for indentation, or inconsistent indentation levels all cause parse failures.
Why This Error Happens
1. Unquoted value containing a colon ā message: Hello: World ā the second : is misread as a mapping
2. Tab characters in indentation ā YAML requires spaces; tabs cause parse errors
3. Inconsistent indentation ā mixing 2-space and 4-space indentation in the same block
4. Colon in flow mapping without quotes ā {key: value: extra} is invalid
5. Missing space after colon ā key:value instead of key: value
Step-by-Step Diagnosis
Step 1 ā Check for colons in unquoted values
# WRONG:
title: My App: The Sequel
# RIGHT:
title: "My App: The Sequel"
title: 'My App: The Sequel'
Step 2 ā Check for tabs
# Find tabs in a YAML file
grep -P "\t" config.yaml
# Or in editors: show whitespace characters
Step 3 ā Validate indentation consistency
# WRONG ā mixed 2 and 4 spaces:
parent:
child1: value1
child2: value2 # This is 4 spaces ā inconsistent!
# RIGHT ā consistent 2-space indentation:
parent:
child1: value1
child2: value2
Solutions
Solution 1 ā Quote strings that contain special characters
# These all need quoting:
message: "Error: connection refused"
url: "https://example.com/path?key=value"
regex: "[a-z]+: \d+"
version: "1.0" # Numbers that should be strings
Solution 2 ā Replace tabs with spaces
# Replace all tabs with 2 spaces
sed -i 's/\t/ /g' config.yaml
# Or in VS Code: Edit > Convert Indentation to Spaces
Solution 3 ā Use block scalars for multiline strings
# Literal block (| preserves newlines):
script: |
#!/bin/bash
echo "Hello"
exit 0
# Folded block (> collapses newlines):
description: >
This is a long description that
will be joined into one line.
Solution 4 ā Use a YAML linter
pip install yamllint
yamllint config.yaml
Real-World Examples
Docker Compose ā environment variable with URL:
# WRONG:
environment:
DATABASE_URL: postgresql://user:pass@host:5432/db
# RIGHT (URL contains colons):
environment:
DATABASE_URL: "postgresql://user:pass@host:5432/db"
GitHub Actions ā step name with colon:
# WRONG:
- name: Build: production
run: npm run build
# RIGHT:
- name: "Build: production"
run: npm run build
Quick Reference ā YAML Special Characters That Need Quoting
| Character | Example value | When to quote |
|---|---|---|
: | "http://example.com" | Always if followed by space |
# | "value # not a comment" | If after a space |
{ } | "{ inline: map }" | In plain scalars |
[ ] | "[a, b, c]" | In plain scalars |
> ` | ` | "> text" |
Prevent This Error in the Future
1. Use a YAML-aware editor with syntax highlighting and validation (VS Code with the YAML extension).
2. Quote anything that looks like a URL, path, or sentence ā when in doubt, quote it.
3. Run yamllint in CI to catch YAML errors before deployment.
Use ToolNinja to Debug Faster
The JSON-YAML converter validates YAML and converts between formats ā paste your YAML to instantly see if it parses correctly and what the resulting structure looks like.