Debugging Ansible Playbooks
Four techniques cover almost every Ansible problem: raise the verbosity, print the variable, assert what you assumed, and ask the inventory what it thinks. This works through all four, and finishes with the distinction between an error that --syntax-check catches and one it cannot.
Scale and Debugging Guide 39 of 45 Intermediate
- OSUbuntu 26.04 LTS
- ansible-core2.20.1
- Python3.14.4
- TimeAbout 15 min
Verbosity is cumulative: -v adds the full result of each task, -vv adds task and handler details, -vvv adds connection information including the exact ssh command, and -vvvv adds connection plugin debugging. -vvv is the level worth reaching for; -vvvv is rarely readable.
| Server Name | IP Address | OS | Roles | CPU | RAM | HDD |
|---|---|---|---|---|---|---|
| ANS-CTL01 | 192.168.0.36 | Ubuntu 26.04 LTS | Ansible Control Node | 2 Core | 3 GB | 50 GB |
| ANS-A01 | 192.168.0.37 | Ubuntu 26.04 LTS | Managed Node (group: web) | 2 Core | 3 GB | 50 GB |
| ANS-B01 | 192.168.0.38 | Ubuntu 26.04 LTS | Managed Node (group: db) | 2 Core | 3 GB | 50 GB |
This guide includes
Use this when a playbook ran and did something you did not intend. This matters because four techniques cover almost every Ansible problem - and knowing which to reach for first is most of the speed.
- raising verbosity, and knowing what each level actually adds
- choosing between
debug: varanddebug: msg - using
assertto fail loudly and early rather than quietly and late - asking what a host actually thinks, three different ways
- telling a syntax error apart from a runtime one
Before you start
- A control node configured as shown in the first step.
- The session runs several diagnostic playbooks and changes nothing on the managed nodes.
-
The configuration this guide assumes
-
The verbosity levels
-
debug var versus debug msg
-
assert fails loudly and early
-
What does this host actually think
-
A syntax error versus a runtime error