AnsibleByExample

Ansible Debugger — Interactive Debugging for Failed Tasks

Beginneransibledebuggertroubleshootingplaybook
2024-01-014By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

What is the Ansible Debugger?

The Ansible debugger is an interactive prompt that activates when a task fails (or always, depending on configuration). It lets you inspect variables, modify arguments, and retry the task without restarting the entire playbook.

Enable the Debugger

Per-Play

- name: Deploy application
  hosts: webservers
  debugger: on_failed
  tasks:
    - name: Start service
      ansible.builtin.service:
        name: myapp
        state: started

Per-Task

- name: Copy configuration
  ansible.builtin.template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
  debugger: on_failed

Global (ansible.cfg)

[defaults]
enable_task_debugger = true

Via Environment Variable

ANSIBLE_ENABLE_TASK_DEBUGGER=true ansible-playbook site.yml

Debugger Strategies

StrategyWhen debugger activates
alwaysAfter every task
neverNever (default)
on_failedOnly on task failure
on_unreachableWhen host is unreachable
on_skippedWhen task is skipped

Debugger Commands

When the debugger activates, you get an interactive prompt:

[server1] TASK: Start service (debug)>
CommandShortDescription
printpPrint variable or task info
task.args[key] = value—Modify task arguments
task_vars[key] = value—Modify task variables
redorRetry the task with current args
continuecContinue to next task (mark as failed)
quitqQuit the playbook
update_taskuUpdate task from modified args

Practical Example: Fixing a Typo

- name: Playbook with a typo
  hosts: localhost
  debugger: on_failed
  vars:
    message: "Hello from Ansible!"
  tasks:
    - name: Display the message
      ansible.builtin.debug:
        msg: "{{ massage }}"  # Typo! Should be 'message'

When this fails:

[localhost] TASK: Display the message (debug)> p task.args
{'msg': '{{ massage }}'}

[localhost] TASK: Display the message (debug)> p task_vars['message']
'Hello from Ansible!'

[localhost] TASK: Display the message (debug)> task.args['msg'] = '{{ message }}'

[localhost] TASK: Display the message (debug)> r
ok: [localhost] => {
    "msg": "Hello from Ansible!"
}

Inspecting Variables

# Print all task arguments
(debug)> p task.args

# Print a specific variable
(debug)> p task_vars['my_variable']

# Print host facts
(debug)> p task_vars['ansible_distribution']

# Print the result of the failed task
(debug)> p result._result

# Print the error message
(debug)> p result._result['msg']

Modifying and Retrying

# Fix a wrong file path
(debug)> task.args['dest'] = '/etc/nginx/nginx.conf'
(debug)> r

# Fix a wrong package name
(debug)> task.args['name'] = 'nginx'
(debug)> r

# Set a missing variable
(debug)> task_vars['db_port'] = 5432
(debug)> r

Real-World Debugging Workflow

---
- name: Deploy web application
  hosts: webservers
  debugger: on_failed
  tasks:
    - name: Install dependencies
      ansible.builtin.apt:
        name: "{{ packages }}"
        state: present
      vars:
        packages:
          - nginx
          - python3-pip
          - python3-venv

    - name: Deploy app config
      ansible.builtin.template:
        src: "{{ app_config_template }}"
        dest: /etc/myapp/config.yml
        owner: myapp
        group: myapp
        mode: '0640'

    - name: Start application
      ansible.builtin.systemd:
        name: myapp
        state: started
        enabled: true

If the template task fails (template not found), the debugger lets you:

  1. p task.args — see which template path it tried
  2. Fix the path: task.args['src'] = 'templates/config.yml.j2'
  3. r — retry without restarting the playbook

Tips

  • Use on_failed in development, never in production
  • Don't leave debugger enabled in CI/CD — it blocks on stdin
  • Combine with --step to step through tasks one at a time: ansible-playbook site.yml --step
  • Use -vvv alongside debugger for maximum visibility

Debugger vs Other Debugging Tools

ToolBest For
debugger: on_failedInteractive fix-and-retry
debug modulePrint variables during execution
--check --diffDry run to preview changes
--stepExecute tasks one at a time
-vvvVerbose connection/execution output
ansible-lintCatch issues before running

Conclusion

The Ansible debugger turns playbook failures from frustration into learning moments. Enable it with debugger: on_failed, use p to inspect, fix the issue, and r to retry — all without restarting your playbook.

All Tutorials