Ansible Debugging
Every automation engineer meets failing playbooks. A missing variable, a wrong indentation, or a blocked network port can stop a run. Good debugging follows a calm routine: read the message, narrow the problem, and test one idea at a time. Compare the process to a doctor who asks about symptoms, runs a simple test, and moves to deeper checks. Ansible provides tools for every stage.
Diagram: The Debugging Ladder
Level 1 ┌───────────────────────────┐
│ Read the error message │
└─────────────┬─────────────┘
▼
Level 2 ┌───────────────────────────┐
│ --syntax-check / lint │
└─────────────┬─────────────┘
▼
Level 3 ┌───────────────────────────┐
│ debug module and -v │
└─────────────┬─────────────┘
▼
Level 4 ┌───────────────────────────┐
│--check / --step / debugger│
└─────────────┬─────────────┘
▼
Level 5 ┌───────────────────────────┐
│ -vvvv connection details │
└───────────────────────────┘
Read the Error Message
Ansible prints the failing task, the host, and a message. The line number points to the area of the YAML file that caused the problem. Many errors fall into a few groups.
| Message Clue | Likely Cause | Fix |
|---|---|---|
| UNREACHABLE | SSH or network problem | Test with ssh and ansible -m ping |
| mapping values are not allowed | YAML indentation or colon error | Fix spacing, quote the value |
| 'x' is undefined | Variable missing | Define it or use the default filter |
| Permission denied | Missing become or wrong user | Add become: true |
| No package matching | Wrong package name or no repo | Check the distribution name |
| Module not found | Collection not installed | Install the collection |
Check Syntax and Style
ansible-playbook site.yml --syntax-check
ansible-lint site.yml
yamllint site.yml
Use the Debug Module
The debug module prints variables and messages during a run.
- name: Run a command
ansible.builtin.command: uptime
register: uptime_result
- name: Show the full result
ansible.builtin.debug:
var: uptime_result
- name: Show only the output line
ansible.builtin.debug:
msg: "{{ uptime_result.stdout }}"
- name: Show detail only with extra verbosity
ansible.builtin.debug:
var: ansible_facts
verbosity: 2
The register keyword captures module output in a variable. Fields such as stdout, stderr, rc, and changed reveal what happened.
Raise the Verbosity
| Flag | Shows |
|---|---|
| -v | Task results |
| -vv | Task input values |
| -vvv | Connection attempts |
| -vvvv | Full SSH commands and plugin loading |
Practice Safe Test Runs
ansible-playbook site.yml --check --diff
ansible-playbook site.yml --step
ansible-playbook site.yml --start-at-task "Install nginx"
ansible-playbook site.yml --limit web1
ansible-playbook site.yml --list-tasks
--checkpredicts changes without applying them--diffshows file differences--stepasks before each task--limitrestricts the run to one host or group
The Interactive Debugger
Enable the task debugger to stop on a failure and inspect values.
- hosts: web1
debugger: on_failed
tasks:
- name: Install a package
ansible.builtin.package:
name: nginxx
state: present
At the (debug) prompt, type p task.args to print task arguments, task.args['name'] = 'nginx' to fix a value, and r to rerun the task. Type q to quit.
Test Connections Separately
ansible web1 -m ansible.builtin.ping -vvv
ssh -v deploy@web1
ansible-inventory --list
ansible-config dump --only-changed
Habits That Save Time
- Change one thing between runs
- Reproduce the failure on one host with
--limit - Keep playbook tasks small and well named
- Store logs with the
log_pathsetting inansible.cfg - Read the module documentation with
ansible-doc
Try This
Create a playbook with a mistake: a misspelled package name or a missing variable. Run the playbook and read the error. Add a debug task and a -vv flag to find the root cause. Fix the playbook and confirm a clean run.
Summary
Debugging works best as a ladder: read the message, check syntax, print values, run safe previews, and increase verbosity. The debug module, register, check mode, step mode, and the task debugger reveal hidden state. Test connections and configuration separately from playbook logic to isolate the cause.
