AnsibleByExample

Fix Ansible Jinja2 & Inventory Errors

AdvancedAnsibleJinja2playbook errorstroubleshooting
2024-01-016By Luca Berton

Lesson 1 of 25 in AWS Automation

AWS with Ansible — full curriculum
  1. 1. AWS Basics for Ansible
  2. 2. Installing the amazon.aws Collection and boto3
  3. 3. AWS Credentials and Profiles: Safe Configuration
  4. 4. Your First AWS Playbook: Regions, Tags and Idempotency
  5. 5. AWS Dynamic Inventory with the aws_ec2 Plugin
  6. 6. Grouping and Filtering Hosts with keyed_groups and Filters
  7. 7. Provisioning EC2 Instances
  8. 8. AMIs and Launch Templates
  9. 9. Building VPC Networks with Ansible
  10. 10. Security Groups and Network Access Control
  11. 11. Elastic IPs and Load Balancers
  12. 12. S3 Buckets and Object Management
  13. 13. IAM Users, Roles and Policies
  14. 14. RDS Databases with Ansible
  15. 15. Route 53 DNS Automation
  16. 16. CloudWatch Monitoring and Alarms
  17. 17. Managing Secrets: Secrets Manager, SSM Parameter Store and Ansible Vault
  18. 18. Post-Provisioning Configuration with Roles
  19. 19. Bridging Provisioning and Configuration: add_host and wait_for
  20. 20. Auto Scaling Groups and Rolling Updates
  21. 21. Validating Infrastructure with Assertions and Health Checks
  22. 22. Error Handling and Rollback in AWS Playbooks
  23. 23. Structuring a Reusable AWS Automation Project
  24. 24. Cost Control and Teardown Playbooks
  25. 25. Capstone: Provision and Configure a Multi-Tier AWS Application
View path overview →

Introduction

Ansible playbook errors can be frustrating, especially when the error message isn't immediately clear. The most common categories are Jinja2 syntax errors (unbalanced blocks, incorrect quoting) and inventory parsing warnings (no valid hosts found). This guide covers systematic troubleshooting for both.

Jinja2 Syntax Errors

Unbalanced Block or Quote

The most common Jinja2 error:

ERROR! Syntax Error while loading YAML.
  found unbalanced jinja2 block or quote

Common causes:

ProblemExampleFix
Missing closing }}{{ var }{{ var }}
Missing closing %}{% if x %{% if x %}
Unmatched quotes inside variable"{{ "hello" }}""{{ 'hello' }}"
Variable at start of value{{ var }} as YAML value"{{ var }}" — must be quoted

Variables Must Be Quoted

In YAML, a value starting with {{ must be quoted:

# WRONG — YAML parser interprets {{ as a mapping
- name: Set variable
  ansible.builtin.debug:
    msg: {{ my_var }}

# CORRECT — quoted
- name: Set variable
  ansible.builtin.debug:
    msg: "{{ my_var }}"

Nested Quotes

When Jinja2 expressions contain strings, alternate quote types:

# WRONG — conflicting double quotes
msg: "{{ "hello world" }}"

# CORRECT — single quotes inside double
msg: "{{ 'hello world' }}"

# CORRECT — double quotes inside single
msg: '{{ "hello world" }}'

Quoting in Shell Commands

# WRONG — unbalanced Jinja2
- name: Fetch console output
  ansible.builtin.command: >
    aws ec2 get-console-output --region {{ aws_region }} --instance-id {{ item[2] }}

# CORRECT — variables quoted
- name: Fetch console output
  ansible.builtin.command: >
    aws ec2 get-console-output --region "{{ aws_region }}" --instance-id "{{ item[2] }}"

Multiline Jinja2 Expressions

# WRONG — missing closing tag
- name: Complex condition
  ansible.builtin.debug:
    msg: "Result is {{ 'yes' if condition else 'no'"

# CORRECT
- name: Complex condition
  ansible.builtin.debug:
    msg: "Result is {{ 'yes' if condition else 'no' }}"

Inventory Parsing Errors

"Unable to parse as an inventory source"

[WARNING]: Unable to parse /etc/ansible/hosts as an inventory source
[WARNING]: No inventory was parsed, only implicit localhost is available

Common causes and fixes:

No Inventory Specified

# WRONG — no inventory
ansible-playbook site.yml

# CORRECT — specify inventory
ansible-playbook site.yml -i inventory.ini

# CORRECT — set in ansible.cfg
[defaults]
inventory = ./inventory

Invalid Inventory Format

# WRONG — missing group brackets
webserver1
webserver2

# CORRECT
[webservers]
webserver1
webserver2

YAML Inventory Syntax Error

# WRONG — hosts is a string, not dict
all:
  hosts: server1

# CORRECT
all:
  hosts:
    server1:
      ansible_host: 192.168.1.10

File Permissions

# Check permissions
ls -la inventory.ini

# Fix if needed
chmod 644 inventory.ini

"Could not match supplied host pattern"

[WARNING]: Could not match supplied host pattern, ignoring: webservers

Fix: The group name in your playbook doesn't match any group in the inventory. Check spelling and case.

Systematic Debugging Process

Step 1: Syntax Check

ansible-playbook site.yml --syntax-check

This catches YAML and Jinja2 errors without executing anything.

Step 2: Lint Your Playbook

ansible-lint site.yml

Catches common mistakes, best practice violations, and deprecated syntax.

Step 3: Verbose Mode

# Increasing verbosity levels
ansible-playbook site.yml -v      # Basic verbose
ansible-playbook site.yml -vv     # More detail
ansible-playbook site.yml -vvv    # SSH debugging
ansible-playbook site.yml -vvvv   # Connection plugin debugging

Step 4: Check Mode (Dry Run)

ansible-playbook site.yml --check --diff

Shows what would change without actually changing anything.

Step 5: Start at a Specific Task

ansible-playbook site.yml --start-at-task "Deploy config"

Step 6: Step Through Tasks

ansible-playbook site.yml --step

Prompts before each task — answer y/n/c (yes/no/continue without asking).

Common Error Patterns and Solutions

"Conditional is not a valid Jinja2 expression"

# WRONG — when already evaluates Jinja2, don't add {{ }}
when: "{{ my_var == 'value' }}"

# CORRECT
when: my_var == 'value'

"dict object has no attribute"

# WRONG — trying to access nested key that doesn't exist
msg: "{{ result.stdout_lines.first }}"

# CORRECT — use default filter
msg: "{{ result.stdout_lines | first | default('N/A') }}"

"undefined variable"

# Use default filter to handle missing variables
msg: "{{ optional_var | default('fallback_value') }}"

# Or check if defined
when: my_var is defined

YAML Indentation Errors

# WRONG — tasks not indented under play
- name: My play
  hosts: all
tasks:                    # Should be indented!
  - name: Do something

# CORRECT
- name: My play
  hosts: all
  tasks:
    - name: Do something

Debugging Variables

- name: Debug variable type
  ansible.builtin.debug:
    msg: "Type: {{ my_var | type_debug }}, Value: {{ my_var }}"

Dump All Variables

- name: Show all variables
  ansible.builtin.debug:
    var: hostvars[inventory_hostname]

- name: Run command
  ansible.builtin.command: ls /tmp
  register: result

- name: Show full result
  ansible.builtin.debug:
    var: result

Prevention Best Practices

  1. Always quote Jinja2 expressions — "{{ var }}" not {{ var }}
  2. Use --syntax-check before running — catches errors instantly
  3. Use ansible-lint — catches more issues than syntax-check
  4. Use | default() for optional variables — prevents undefined errors
  5. Test with --check --diff — verify changes before applying
  6. Use VS Code Ansible Extension — real-time syntax validation
  7. Use ansible-doc — check module parameters: ansible-doc ansible.builtin.copy

Conclusion

Most Ansible errors fall into two categories: Jinja2 syntax (quoting, balanced blocks, nested quotes) and inventory parsing (missing files, wrong format, typos in group names). The systematic debugging process — --syntax-check → ansible-lint → verbose mode → check mode — catches nearly all issues before they reach production. The single most impactful habit: always quote Jinja2 expressions in YAML values.

All Tutorials