Ansible Troubleshooting: Common Errors, Solutions, and Debug Techniques
By Luca Berton · Published 2024-01-01 · Category: installation
Fix common Ansible errors fast. Debug playbook failures, SSH connection issues, module errors, variable problems, and permission errors. Master ansible-playbook debug mode, verbose output, and systematic troubleshooting.
Debug Modes
Verbosity Levels
Debug Module
Debugger
Debugger commands: • p task — print task info • p task.args — print task arguments • p host — print current host • p result — print task result • p vars — print all variables • r — retry the task • c — continue to next task • q — quit
Check Mode (Dry Run)
Step Mode
Connection Errors
"UNREACHABLE! => No route to host"
Fixes:
"Permission denied (publickey,password)"
Fixes:
"Host key verification failed"
SSH Timeout
Module Errors
"MODULE FAILURE: No module named 'xyz'"
"Unsupported parameters"
Fix: Check documentation for correct parameter names and your Ansible version:
"Missing required arguments"
Fix: Read the module docs and supply all required parameters:
"No such file or directory"
Variable Errors
"undefined variable"
Fixes:
"dict object has no attribute"
Variable Precedence Issues
Permission Errors
"sudo: a password is required"
"Failed to set permissions on the temporary files"
Fix: Enable pipelining or set allow_world_readable_tmpfiles:
Playbook Errors
"Syntax Error"
"ERROR! Unexpected Exception during execution"
Usually a Python issue on the control node:
"Conditional check failed"
Task Hanging / Never Completing
Systematic Troubleshooting
Step 1: Isolate the Problem
Step 2: Check the Basics
Step 3: Read the Full Error
Ansible error messages contain useful details. Look for: • msg: Human-readable error description • stderr: Command stderr output • stdout: Command stdout output • rc: Return code (non-zero = failure) • module_stderr: Module-specific errors
Step 4: Use ansible-config
Logging
FAQ
How do I debug a specific task?
Use ansible-playbook site.yml --start-at-task "Task Name" -vvv --limit single-host. This runs from that specific task with full debugging on a single host.
Why does my playbook work manually but fail in cron?
Cron has a minimal environment. Common issues: (1) PATH doesn't include /usr/local/bin, (2) SSH agent isn't available, (3) ansible.cfg isn't found. Fix: use full paths, specify ANSIBLE_CONFIG, and use --private-key instead of ssh-agent.
How do I find which variable is overriding mine?
Use ansible-inventory --host hostname --yaml to see effective variables. Add -vvv to playbook runs to see where each variable is loaded from. Remember the variable precedence order.
How do I handle intermittent failures?
Use retries and delay:
Conclusion
Ansible troubleshooting follows a consistent pattern: increase verbosity (-vvv), isolate the problem (single host, single task), check the basics (connectivity, permissions, Python), read the full error message, and fix systematically. Enable profile_tasks callback to identify slow tasks, use --check --diff for safe previewing, and ansible-lint to catch issues before they hit production.
Related Articles • Ansible Performance Tuning • Ansible Lint Complete Guide • Ansible Documentation Complete Guide • Ansible Handlers Complete Guide • Install Ansible Complete Guide • Fix 'Use loop or with_' Deprecated Error • Failed Ansible Installation on Amazon Linux 2022 • Handle Non-Compliant Variable Names • Handle Variable Dependencies Without Breaking • Fixing Kubernetes PersistentVolume Error
Category: installation