---
title: "Tapping Ansible Debug to Troubleshoot Playbooks and Roles"
description: "Learn how to troubleshoot Ansible playbooks through ansible debug and roles to always get smooth automation executions in this step-by-step tutorial!"
canonical: "https://adamtheautomator.com/ansible-debug/"
---

# Tapping Ansible Debug to Troubleshoot Playbooks and Roles

> Learn how to troubleshoot Ansible playbooks through ansible debug and roles to always get smooth automation executions in this step-by-step tutorial!

Source: https://adamtheautomator.com/ansible-debug/

---

ATA Learning

Tap to hide

[

ATA Learning

](/)

*   [Home](/)
*   [Tutorials](/tutorials/)
*   [Instructors](/author/)
*   [Advertising](/advertising/)
*   [Recommended Resources](/resources/)
*   [About Adam](/about-adam/)

Search for:  

*   [](https://twitter.com/adbertram)
*   [](https://github.com/Adam-the-Automator)
*   [](https://www.linkedin.com/company/adam-the-automator-llc)
*   [](/feed/)

![Tapping Ansible Debug to Troubleshoot Playbooks and Roles](https://adamtheautomator.com/wp-content/uploads/2022/04/Tapping-Ansible-Debug-to-Troubleshoot-Playbooks-and-Roles-.jpg)

# Tapping Ansible Debug to Troubleshoot Playbooks and Roles

[![](https://secure.gravatar.com/avatar/2788bb1a3f735603f81eca51d68daec56a9d97e805a10268fb2c20afcc76b81b?s=192&d=mm&r=g)Nicholas Xuan Nguyen](https://adamtheautomator.com/author/nicholas-xuan-nguyen/)15 April 20227 min. read

Categories: [DevOps](/category/devops/)

Tags:[Ansible](/tag/ansible/)

Table of Contents

*   [Prerequisites](#prerequisites)
*   [Troubleshooting Using the Command-Line Options](#troubleshooting-using-the-command-line-options)
*   [Enabling Playbook Debugger to Start When Running a Playbook](#enabling-playbook-debugger-to-start-when-running-a-playbook)
*   [Troubleshooting with the Ansible Debug](#troubleshooting-with-the-ansible-debug)
*   [Conclusion](#conclusion)

If you are reading this tutorial, chances are you use Ansible for automation in your daily workloads. But as with all software, [Ansible](https://www.ansible.com/) can occasionally have issues. Worry not, though. Command-line options and Ansible debug can help!

In this tutorial, you’ll learn to troubleshoot playbooks, resolving any potential issues as quickly as possible, so you can get back to automating.

Read on and smoothly run your playbooks without messing things up!

## **Prerequisites**

This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have the following.

*   An Ansible control node with Ansible installed.

Related:[How to Setup Ansible (Ubuntu, RHEL, CentOS,](https://adamtheautomator.com/install-ansible/)

*   A managed node or host that the control node can access via SSH. Here’s a [guide](https://adamtheautomator.com/powershell-ssh/) in starting SSH with Powershell.

Related:[Getting Started using SSH with PowerShell](https://adamtheautomator.com/powershell-ssh/)

*   Python 3.x is installed on both the control node and the managed node (host).

Related:[How Do You Install Python 3.6?](https://adamtheautomator.com/install-python-36/)

*   An [inventory file set up](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html) and populated with hostnames or IP addresses of your managed host.

## Troubleshooting Using the Command-Line Options

Running into errors when executing your playbooks can be a pain. Naturally, you’d need a way to troubleshoot and debug your playbooks to avoid messing things up. Luckily, Ansible lets you troubleshoot playbooks by appending options in the [`ansible-playbook`](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html) command.

By default, Ansible has a built-in syntax checker called [`--syntax-check`](https://docs.ansible.com/ansible/latest/cli/ansible-playbook.html). This syntax checker is a great way to catch mistakes in your YML files before running your playbooks.

To demonstrate how the syntax checker works:

1\. Create a YAML file (playbook) in your current working directory on your control node using your preferred text editor and populate the following code. You can name the file as you like, but for this tutorial, the file is named _create\_user.yml_.

Related:[How to Build (And Actually Understand) a Solid Ansible Playbook](https://adamtheautomator.com/ansible-playbook-example/)

The code below runs a task to create a user named ata on your managed node.

```yaml
---
- name: Ansible Create user
  hosts: all
  become: true

  tasks: # Runs a task to create a user named 'ata'
   - name: Create ata user
     user:
        name: ata
        state: present
```

Related:[How to Secure Ansible Playbooks with Ansible Become](https://adamtheautomator.com/ansible-become/)

2\. Next, open your terminal, and run the following command to test the `create_user.yml` playbook for syntax errors (`--syntax-check`).

The syntax checker parses the YAML file and looks for any potential errors without running any of your playbook tasks.

```bash
ansible-playbook --syntax-check create_user.yml
```

If your playbook passes the syntax check without errors, you’ll see the name of your playbook (create\_user.yml) as in the following screenshot. But if there are errors in your playbook, you’ll see an error message and the line number where the error occurred explicitly (step four).

![Checking Syntax Errors in Playbook](https://adamtheautomator.com/wp-content/uploads/2022/04/image-239.png)

Checking Syntax Errors in Playbook

3\. Open the _create\_user.yml_ file in a text editor and add a line that says “**This is an error!!!**” at the bottom to cause a syntax error, then save and close the file.

![Adding a Random Line to Cause an Error](https://adamtheautomator.com/wp-content/uploads/2022/04/image-240.png)

Adding a Random Line to Cause an Error

4\. Now, rerun the below command to perform a `--syntax-check` on your playbook (`create_user.yml`).

```bash
ansible-playbook --syntax-check create_user.yml
```

As you can see below, the syntax checker caught the error and displayed the message Syntax Error while loading YAML, followed by the line number where the error occurred (12).

![Checking Syntax of Playbook (Caught an Error)](https://adamtheautomator.com/wp-content/uploads/2022/04/image-241.png)

Checking Syntax of Playbook (Caught an Error)

5\. Go back to the _create\_user.yml_ file and remove the random line you added to cause an error. Save the changes you made and close the file.

6\. Next, rerun the below command to perform a `--syntax-check` to ensure there are no more errors in your playbook (`create_user.yml`).

```bash
ansible-playbook --syntax-check create_user.yml
```

![Rechecking Syntax on Playbook](https://adamtheautomator.com/wp-content/uploads/2022/04/image-242.png)

Rechecking Syntax on Playbook

7\. Run the below command to perform a dry run (`--check`) on your playbook (`create_user.yml`).

Performing a dry run is a great way to test your playbook for errors before running it on live systems. A dry run lets you simulate running a playbook without changing any data or taking any action on the hosts.

```bash
ansible-playbook --check create_user.yml
```

![Performing a Dry Run on Playbook](https://adamtheautomator.com/wp-content/uploads/2022/04/image-243.png)

Performing a Dry Run on Playbook

> _Note that not all modules support the –check flag. For example, modules that change data or the system do not support the –check flag._

> _Tasks using modules that support the –check flag shows the output of running the task on target hosts and any changes made if the module were executed._

8\. After the dry run, execute the below command to connect to one of the hosts via `ssh` to verify no changes are made on the managed hosts. Replace `root` and `159.223.233.161` with your managed host’s actual username and IP address.

```bash
ssh root@159.223.223.161
```

![Connecting to Managed Host via SSH](https://adamtheautomator.com/wp-content/uploads/2022/04/image-244.png)

Connecting to Managed Host via SSH

9\. Now, run the [`tail`](https://manpages.ubuntu.com/manpages/bionic/man1/tail.1.html) command below to check if the user ata was created in the `/etc/passwd` file.

```bash
tail /etc/passwd
```

You’ll see that no ata user was created after the dry run, as shown below since the dry run only checked for errors without actually running the playbook.

![Verifying No User Named ata Exists](https://adamtheautomator.com/wp-content/uploads/2022/04/image-245.png)

Verifying No User Named ata Exists

10\. Finally, run `logout` to leave the managed host.

```bash
logout
```

![Logging out from the Managed Host](https://adamtheautomator.com/wp-content/uploads/2022/04/image-246.png)

Logging out from the Managed Host

## Enabling Playbook Debugger to Start When Running a Playbook

You’ve seen that troubleshooting playbooks using options in the `ansible-playbook` command works like a charm. But apart from those options, Ansible also has the built-in [playbook debugger](https://docs.ansible.com/ansible/latest/user_guide/playbooks_debugger.html).

The Ansible playbook debugger is a powerful tool that allows you to step through your playbook and see the results of each task as they execute.

1\. Run the below command to create a config file called _ansible.cfg_ in your home directory (the root directory in this example). This file contains configuration options for the playbook debugger.

```bash
ansible-config init --disabled > ansible.cfg
```

![Creating a Config File Called ansible.cfg](https://adamtheautomator.com/wp-content/uploads/2022/04/image-247.png)

Creating a Config File Called _ansible.cfg_

2\. Next, open the _ansible.cfg_ file in a text editor and add the **enable\_task\_debugger = True** line under the **defaults** section, as shown below. This setting enables the playbook debugger to start automatically when you run the playbook. Save the changes and close the file.

Once the playbook debugger is enabled, any failed or unreachable task will begin the inline debugger interaction prompt.

![Enabling the Playbook Debugger](https://adamtheautomator.com/wp-content/uploads/2022/04/image-248.png)

Enabling the Playbook Debugger

3\. Run the below command to ensure that you are using the correct config file, which should be _ansible.cfg_ in your home directory, as shown below.

```bash
ansible -­-version
```

![Ensuring the Correct Config File is Set](https://adamtheautomator.com/wp-content/uploads/2022/04/image-249.png)

Ensuring the Correct Config File is Set

## Troubleshooting with **the Ansible Debug**

Since you’ve set the playbook debugger to start whenever you run a playbook, you can now put the `debugger` keyword anywhere in a playbook. Doing so enables task debugging, such as playbooks, roles, blocks, or even individual tasks.

The `debugger` keyword supports five values, including the most commonly used value (`on_failed`) when debugging a play:

<table><tbody><tr><td>Value</td><td>Result</td></tr><tr><td>always</td><td>The debugger will always run when specified, regardless of the outcome.</td></tr><tr><td>never</td><td>The debugger will never run, regardless of the outcome.</td></tr><tr><td>on_failed</td><td>The debugger will only run if the task fails (for debugging task failures).</td></tr><tr><td>on_unreachable</td><td>The debugger will only run if the task is unreachable. Use this value when your managed host is unreachable or when a task has a timeout.</td></tr><tr><td>on_skipped</td><td>The debugger will only run if the task skipped itself by execution</td></tr></tbody></table>

To troubleshoot a playbook with Ansible debug:

1\. Create a _debugger\_demo.yml_ playbook in your favorite editor, and populate the following code. Save the changes and close the playbook.

The code below installs a package called does\_not\_exist on the managed host using yum. But since the package doesn’t exist in the yum repository, the task will fail and invoke the debugger.

```bash
---
- name: Debugger demo
  hosts: all
	# Enable debugging for a task.
  debugger: on_failed # Invokes the debugger if the task fails
  vars: # Set a variable to hold the package name
    - pkg_name: does_not_exist 
  tasks:
   - name: Install a package # Installs the package the pkg_name variable holds
     yum: 
      name: "{{ pkg_name }}" 
      state: present
```

2\. Next, run the below command to execute the playbook (`debugger_demo.yml`).

```bash
ansible-playbook debugger_demo.yml
```

The task fails since the _debugger\_demo.yml_ playbook tries to install a package that doesn’t exist, as shown below. You’ll also notice an inline debugger prompt.

![Attempting to Execute the debugger\_demo.yml Playbook](https://adamtheautomator.com/wp-content/uploads/2022/04/image-250.png)

Attempting to Execute the _debugger\_demo.yml_ Playbook

Once you invoke the debugger, you will have access to many debugger arguments/commands that help you step through the playbook, as shown below.

<table><tbody><tr><td>Command</td><td>Shortcut</td><td>Action</td></tr><tr><td>print</td><td>p</td><td>Print the value of a variable. For example, you can use it to print the value of a task’s result.</td></tr><tr><td>task.args[key] = value</td><td>no shortcut</td><td>Sets the value of a task’s argument directly in the debugger inline prompt. This argument is useful when testing the behavior of a task with different arguments.<br><br>For example, to set the value of a task’s hostname argument to “www.example.com”, use this argument like so: task.args[‘hostname’] = ‘www.example.com’.</td></tr><tr><td>task_vars[key] = value</td><td>no shortcut</td><td>Updates the task variables (you must use update_task next)</td></tr><tr><td>update_task</td><td>u</td><td>Recreate a task with updated task variables.</td></tr><tr><td>redo</td><td>r</td><td>Restarts the playbook from the beginning and reruns the entire play. But any new changes you made to task arguments using the task.args argument will remain in effect.<br><br>You can use this argument to correct any issues you’ve discovered quickly.</td></tr><tr><td>continue</td><td>c</td><td>Continue executing, starting with the next task.</td></tr><tr><td>quit</td><td>q</td><td>Quit the debugger.</td></tr></tbody></table>

3\. Run the below command to inspect what task argument values (`task.args`) are used during task execution.

```bash
p task.args
```

In the output below, you can see the task is using the default values for the name and state arguments. These default values are defined in the vars section of the _debugger\_demo.yml_ playbook. Notice the package name (does\_not\_exist) with a state of present.

![Inspecting Task Arguments](https://adamtheautomator.com/wp-content/uploads/2022/04/image-251.png)

Inspecting Task Arguments

4\. Now, run the following command to update the state argument to a package (`bash`) that exists in the managed host’s repository.

```bash
task.args['name']='bash'
```

At this point, you have a new inline value for the task.args\[‘name’\] argument(bash). You’re no longer using the variable defined in the vars section of the playbook.

5\. Rerun the command below to inspect task argument values and verify the changes.

```bash
p task.args
```

Below, the bash package is now being used as the value for the task argument.

![Verifying Task Argument Changes](https://adamtheautomator.com/wp-content/uploads/2022/04/image-252.png)

Verifying Task Argument Changes

6\. Finally, run the `redo` debugger argument to restart the playbook and rerun the entire play.

```bash
redo
```

This time, the task runs, as shown below. Notice that you get an ok status since the Bash package exists in the managed host’s repository.

![Rerunning the Ansible Task](https://adamtheautomator.com/wp-content/uploads/2022/04/image-253.png)

Rerunning the Ansible Task

## Conclusion

Debugging playbooks can be a challenge, but Ansible provides tools to make the process easier. And in this article, you’ve learned how to use the command-line options and the Ansible debugger to help you step through your playbook and troubleshoot issues.

You also learned to get around the debugger’s arguments/commands to inspect and modify task arguments during playbook execution. At this point, you already have a fully functional Ansible environment and the knowledge required to start debugging your automation.

Why not try the Ansible debugger on some of your playbooks to Ansible [debug network](https://docs.ansible.com/ansible/latest/network/user_guide/network_debug_troubleshooting.html) automation? You’ll find the Ansible debugger is an invaluable tool for troubleshooting issues and understanding the behavior of your automation.

Share this article

[Share on X](https://twitter.com/intent/tweet?url=https%3A%2F%2Fadamtheautomator.com%2Fansible-debug%2F&text=Tapping%20Ansible%20Debug%20to%20Troubleshoot%20Playbooks%20and%20Roles)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fadamtheautomator.com%2Fansible-debug%2F)[Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fadamtheautomator.com%2Fansible-debug%2F)

## Related Posts

![](https://adamtheautomator.com/wp-content/uploads/2021/04/A-Step-by-Step-Guide-to-Getting-Started-with-Ansible-on-Windows.jpg)

### [Mastering Ansible on Windows: Your Go-To Expert Guide](/ansible-on-windows/)

Ansible on Windows made simple. A complete guide to hassle-free installation and configuration, perfect for users seeking quick and effective mastery.

![](https://adamtheautomator.com/wp-content/uploads/2022/10/How-to-Manage-Python-Libraries-with-Ansible-Pip.jpg)

### [How to Manage Python Libraries with Ansible Pip](/ansible-pip/)

Learn how to effectively manage Python libraries with the Ansible Pip module and take control of your Python dependencies!

![](https://adamtheautomator.com/wp-content/uploads/2022/06/Highly-Effective-Automation-with-Ansible-AWX.jpg)

### [Highly Effective Automation with Ansible AWX](/ansible-awx/)

Learn how Ansible AWX can take your Ansible playbooks to the next level and automate all the things with this ATA Learning tutorial!

## Categories

*   [IT Ops](/category/it-ops/)
*   [Cloud](/category/cloud/)
*   [DevOps](/category/devops/)
*   [Home Ops](/category/home-ops/)
*   [Information Security](/category/infosec/)
*   [Software Development](/category/software-development/)

## Site

*   [Home](/)
*   [Tutorials](/tutorials/)
*   [Instructors](/author/)
*   [Advertising](/advertising/)
*   [Recommended Resources](/resources/)
*   [About Adam](/about-adam/)

Copyright 2026© ATA Learning | [Privacy Policy](/privacy/)