Debug Playbook Failures with Verbosity and Check Mode

Intermediate8 min

Diagnose and fix Ansible playbook failures using increased verbosity levels, debug module, check mode, and step-by-step execution.

Prerequisites

-Ansible installed
-A playbook to debug

Steps

Run with increased verbosity

Shows SSH connection details, module arguments, and full return values. Use -vvvv for connection-level debugging.

$ ansible-playbook site.yml -vvv

Start with -v and increase verbosity only if you need more detail. -vvvv shows raw SSH commands.

Use the debug module

Add debug tasks in your playbook to print variable values: 'debug: var=my_variable' or 'debug: msg="Value is {{ my_var }}"'.

$ ansible-playbook -e 'debug_task=true' site.yml

Run in step mode

Prompts you before each task with yes/no/continue, letting you step through the playbook interactively.

$ ansible-playbook site.yml --step

Start at a specific task

Skips all tasks before the named task. Useful when you know which task is failing.

$ ansible-playbook site.yml --start-at-task "Deploy nginx config"

Check for syntax errors

Validates YAML syntax and checks for common mistakes and best practice violations.

$ ansible-playbook site.yml --syntax-check && ansible-lint site.yml

Full Script

full-script.sh

# Ansible troubleshooting workflow
ansible-playbook site.yml --syntax-check
ansible-lint site.yml
ansible-playbook site.yml --check --diff
ansible-playbook site.yml -vvv
ansible-playbook site.yml --step
ansible-playbook site.yml --start-at-task "Deploy nginx config"

FAQ

Discussion

Loading comments...

# Ansible troubleshooting workflow ansible-playbook site.yml --syntax-check ansible-lint site.yml ansible-playbook site.yml --check --diff ansible-playbook site.yml -vvv ansible-playbook site.yml --step ansible-playbook site.yml --start-at-task "Deploy nginx config"