Ansible Syntax Error: Debug & Fix YAML Playbook Errors (Guide)
By Luca Berton · Published 2024-01-01 · Category: installation
Fix Ansible syntax errors in playbooks. Debug YAML indentation, quoting, colons, and common YAML gotchas with step-by-step troubleshooting examples.
Introduction
Today we're going to talk about Ansible troubleshooting and specifically about Syntax Errors. I'm Luca Berton, and welcome to today's episode of Ansible Pilot.
Demo
The best way of talking about Ansible troubleshooting is to jump into a live Playbook to show you practically the syntax error and how to solve it!
Error Code
report.txt:
syntax_error.yml:
Error Execution
Output:
Fix Code
syntax_fix.yml:
Fix Execution
Output:
Conclusion
Now you know better how to troubleshoot the Ansible Syntax Error.
Common Syntax Errors and Fixes
Error 1: "could not find expected ':'"
Cause: Missing colon after a key, or unquoted string containing a colon.
Error 2: "mapping values are not allowed here"
Cause: Usually a colon inside an unquoted string.
Error 3: "did not find expected key"
Cause: Inconsistent indentation within a block.
Error 4: "We were unable to read either as JSON nor YAML"
Cause: Jinja2 variable used without quotes.
Debugging Tools
1. --syntax-check (built-in)
Catches basic YAML and Ansible syntax errors without executing the playbook.
2. yamllint (detailed YAML validation)
Catches indentation issues, trailing spaces, line length, and more.
3. ansible-lint (best practices + syntax)
Goes beyond syntax — checks for deprecated modules, missing name fields, risky practices.
4. VS Code YAML extension
Install "YAML" by Red Hat — provides real-time syntax highlighting and error detection:
Prevention Best Practices Always quote strings with special chars: :, {, }, [, ], #, &, *, !, |, >, ', ", %, @ Use --syntax-check before every run Set up pre-commit hooks with yamllint Use 2-space indentation consistently Never use tabs in YAML files
FAQ
How do I find the exact line with the error?
Ansible usually shows the file and line number. But the actual error is often above the reported line. Look at the preceding 5-10 lines.
Why does my playbook work locally but fail on the server?
Different Ansible versions parse YAML slightly differently. Also check for invisible characters (BOM, Windows line endings):
How do I validate all playbooks in a project?
Check Syntax
Common Syntax Errors
Wrong Indentation
Unquoted Colons
Unquoted Special Characters
Boolean Gotcha
Missing Module Colon
Tab Characters
Debugging Steps
Complex Value Quoting
Multi-Line Strings
Common Error Messages
| Error | Likely Cause | |-------|-------------| | could not find expected ':' | Missing colon or bad indentation | | mapping values are not allowed | Unquoted colon in value | | found character that cannot start | Tab character or special char | | did not find expected key | Indentation mismatch | | found unexpected end of stream | Unclosed quote or bracket | | duplicate key | Same key twice in a mapping |
IDE Setup
Use an editor with YAML support: • VS Code + Ansible extension — real-time syntax validation • vim — set expandtab shiftwidth=2 • PyCharm — YAML/Ansible plugin
FAQ
How do I find tab characters?
Why does when: var == "yes" fail?
YAML may parse yes as boolean before Ansible sees it. Quote the value: when: var == "yes" (the quotes are part of the Jinja2 expression here, which is fine).
Syntax check passes but playbook fails?
--syntax-check only validates YAML structure and Ansible task format. It doesn't check variable values, module parameters, or runtime conditions.
Related Articles • Ansible Template Guide • Ansible for Windows Guide • Ansible Become Guide • Ansible Inventory Guide • Ansible Roles Guide
Category: installation
Watch the video: Ansible Syntax Error: Debug & Fix YAML Playbook Errors (Guide) — Video Tutorial