Ansible Troubleshooting Part2


Ansible Troubleshooting Part 2

In the first blog Ansible Troubleshooting part 1. I showed some basic techniques. Now in this part I show one some more advanced technique.

Ansible Debugger

Ansible contains a debugger that you can use in a running Ansible process. To get some more information. You can use the debugger keyword to enable (or disable) the debugger for a specific play, role, block, or task.

The debugger keyword accepts five values:

Value Description
always Always invoke the debugger, regardless of the outcome.
never Never invoke the debugger, regardless of the outcome.
on_failed Only invoke the debugger if a host is unreachable.
on_skipped Only invoke the debugger if the task is skipped.
1# Example debugger on task level.
2- name: Execute a command
3  ansible.builtin.command: "false"
4  debugger: on_failed
2# Example debugger on play level
3- hosts: all
4  debugger: on_failed
5  gather_facts: no
6  tasks:
1# Example debugger on multiple level. The task level overrides the play level
2- name: Play
3  hosts: all
4  debugger: never
5  tasks:
6    - name: Execute a command
7      ansible.builtin.command: "false"
8      debugger: on_failed

When the play reaches a debug point. I changes the shell to a debug shell. You can use Python command here. Ansible is python under the hood.

printing the values

Then you can check the specific values

What Command
Task name p task
Task input arguments p task.args
Specific input argument for example name p task.args['name']
Task variables p task_vars
Specific task var for example package p task_vars['package]

So you can see the values in the output.

In below example we see that we use p task to print the current task name and p task.args to print the current task arguments.

Ansible-troubleshooting debugger vars
Ansible debugging print task and arguments

changing values

With the debugger you can change the values in runtime. In the example below we make a mistake. The package name is misspelled. We use the the task.args command toc change the values.

 2# This playbook is used as example to show debugger commands. The var package is misspelled. baash instead of bash.
 3- name: debugger advanced example
 4  hosts: all
 5  debugger: on_failed
 6  vars:
 7    package: baash
 8  tasks:
 9    - name: install bash 
10      ansible.builtin.apt:
11        name: "{{ package }}"
12        state: present

Ansible-troubleshooting debugger vars
Var debugging update the arguments

update the vars

In this example we use the task_vars command to update the package variable and update the task and rerun the task.

Ansible-troubleshooting debugger vars
Var debugging update the var

Step trough the play

As you see you can run the task again with redo or r. Or continue the play and go to the next task with c.

Other options to activate the debugger.

As you can read you can activate the debugger with the debugger keyword in the play or task. But you can do this also in the

  • Environment variables
  • Ansible CFG

Enable the debugger in the environment variables

Put the ANSIBLE_ENABLE_TASK_DEBUGGER=True in front of the ansible-playbook command

1ANSIBLE_ENABLE_TASK_DEBUGGER=True ansible-playbook -i localhost, debugger-example2.yml --connection=local

Enable the debugger in the Ansible CFG

Add the following line to the Ansible CFG.

Ansible Debugger in Ansible CFG

enable_task_debugger = True

Using Ansible debugger with free strategy

Using the debugger on the free strategy will cause no further tasks to be queued or executed while the debugger is active. Additionally, using redo on a task to schedule it for re-execution may cause the rescheduled task to execute after subsequent tasks listed in your playbook.


Ansible debugger is very strong tool to troubleshoot some more complex problems and to do some debugging in the play. The examples are easy ones to show the possibilities. Ansible debugger can help you identify issues in your Ansible playbooks more quickly. If you have any questions leave a comment below or contact me. For the possibilities see the about page.

comments powered by Disqus