How to Fix Ansible Playbook Syntax Error

In this tutorial, you'll learn about How to Fix Ansible Playbook Syntax Error. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

Your <a href="/devops/ansible/">Ansible</a>-playbook command fails with ERROR! Syntax Error while loading YAML or mapping values are not allowed in this context. Ansible playbooks are YAML files with extremely strict indentation rules — a single extra space or a tab instead of spaces causes the entire playbook to fail Parsing. The error message usually includes the file name and approximate line number, but the exact problem can be subtle.

Quick Fix

1. Run the built-in syntax checker

ansible-playbook --syntax-check playbook.yml

Expected output (success):

playbook: playbook.yml

Expected output (failure):

ERROR! Syntax Error while loading YAML.
  found a tab character that violate indentation
  in "/home/user/project/playbook.yml", line 7, column 3

2. Fix indentation — use only spaces, never tabs

# Wrong: tab before 'hosts'
- name: Install Nginx
  hosts: webservers
  become: yes
  tasks:
  - name: Install nginx
    apt:
      name: nginx
      state: present

# Right: consistent 2-space indentation
- name: Install Nginx
  hosts: webservers
  become: yes
  tasks:
    - name: Install nginx
      apt:
        name: nginx
        state: present

3. Use Ansible-lint for comprehensive validation

pip install ansible-lint
ansible-lint playbook.yml

Expected output:

Passed with warnings: 0 failure(s), 0 warning(s) on 1 files.

4. Check common YAML pitfalls

# Booleans must be lowercase or use quotes
debug_mode: true        # OK
debug_mode: True        # OK
debug_mode: yes         # OK (Ansible-specific)

# Multiline strings
description: |
  This is a long description
  that spans multiple lines.
  The pipe character keeps newlines.

# Lists and dictionaries
packages:
  - nginx
  - postgresql

vars:
  app_port: 8080
  app_host: "0.0.0.0"  # Quotes for strings that look like numbers

5. Debug with Python's YAML parser

python3 -c "import yaml; yaml.safe_load(open('playbook.yml'))"

Expected output (if valid):

# No output — YAML parsed successfully

Expected output (if invalid):

yaml.scanner.ScannerError: mapping values are not allowed here
  in "playbook.yml", line 10, column 14

6. Convert tabs to spaces across the project

find . -name "*.yml" -o -name "*.yaml" | xargs sed -i 's/\t/  /g'

7. Check for missing or extra colons in dictionary keys

# Wrong: space before colon
wrong_key : value

# Wrong: no space after colon
wrong_key:value

# Correct
correct_key: value

Use a YAML linter to catch these:

pip install yamllint
yamllint playbook.yml

8. Check for missing mandatory fields

Ansible requires name on every task. If a task is missing a name, add one:

- name: Install nginx
  apt:
    name: nginx
    state: present

Prevention

• Configure your editor to use 2-space indentation for YAML and show invisible characters
• Run <a href="/devops/ansible/">Ansible</a>-lint as a pre-commit hook to catch errors before they reach Git
• Run <a href="/devops/ansible/">Ansible</a>-playbook --syntax-check before every playbook execution
• Never use tabs in YAML files — configure your editor to convert tabs to spaces
• Keep playbook files under 200 lines by using import_playbook and include_tasks