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 ClueLikely CauseFix
UNREACHABLESSH or network problemTest with ssh and ansible -m ping
mapping values are not allowedYAML indentation or colon errorFix spacing, quote the value
'x' is undefinedVariable missingDefine it or use the default filter
Permission deniedMissing become or wrong userAdd become: true
No package matchingWrong package name or no repoCheck the distribution name
Module not foundCollection not installedInstall 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

FlagShows
-vTask results
-vvTask input values
-vvvConnection attempts
-vvvvFull 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
  • --check predicts changes without applying them
  • --diff shows file differences
  • --step asks before each task
  • --limit restricts 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_path setting in ansible.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.