ansible-debug

Ansible Debugging

Overview

Ansible errors fall into four categories: connection, authentication, module, and syntax. Systematic diagnosis starts with identifying the category, then isolating the specific cause.

When to Use

• UNREACHABLE errors (SSH/network issues)
• Permission denied or sudo password errors
• MODULE FAILURE messages
• Undefined variable errors
• Template rendering failures
• Slow playbook execution

Error Categories

Category	Symptoms	First Check
Connection	UNREACHABLE	ssh -v user@host
Authentication	Permission denied, Missing sudo password	SSH keys, sudoers config
Module	MODULE FAILURE	Module parameters, target state
Syntax	YAML parse error	Line number in error, indentation

Quick Diagnosis

Connection Errors

# Test SSH directly
ssh -v -i /path/to/key user@hostname

# Test port connectivity
nc -zv hostname 22

# Verify inventory parsing
ansible-inventory --host hostname

Common causes:

• Wrong IP/hostname in inventory
• Firewall blocking port 22
• SSH key permissions (must be 600)

Authentication Errors

# Test with explicit options
ansible hostname -m ping -u user --private-key /path/to/key

# For sudo password issues, either:
ansible-playbook playbook.yml --ask-become-pass
# Or configure NOPASSWD in /etc/sudoers

Module Errors

# Check module documentation
ansible-doc ansible.builtin.copy

# Verify module parameters match your Ansible version
ansible --version

Variable Errors

# Use default filter for optional variables
{{ my_var | default('fallback') }}

# Debug variable values
- ansible.builtin.debug:
    var: problematic_variable

Verbosity Levels

Flag	Shows
-v	Task results
-vv	Task input parameters
-vvv	SSH connection details
-vvvv	Full plugin internals

Start with -v, increase only if needed.

Debugging Commands

# Syntax check only
ansible-playbook --syntax-check playbook.yml

# Dry run
ansible-playbook --check playbook.yml

# Step through tasks
ansible-playbook --step playbook.yml

# Start at specific task
ansible-playbook --start-at-task "Task Name" playbook.yml

# Limit to specific host
ansible-playbook --limit hostname playbook.yml

Common Error Patterns

Error	Cause	Fix
Permission denied (publickey)	SSH key not accepted	Check key permissions, verify authorized_keys
Missing sudo password	become=true without password	Use --ask-become-pass or configure NOPASSWD
No such file or directory	Path doesn't exist	Create parent directories first
Unable to lock (apt/yum)	Package manager locked	Wait for other process, remove stale lock
undefined variable	Variable not defined	Check spelling, use default() filter

Performance Debugging

# ansible.cfg
[defaults]
callback_whitelist = profile_tasks  # Show task timing

[ssh_connection]
pipelining = True                   # Faster SSH

# Skip fact gathering if not needed
- hosts: all
  gather_facts: no