From ansible-skills
Debugs Ansible playbook failures including UNREACHABLE, permission denied, MODULE FAILURE, undefined variables, SSH connection issues, and sudo password errors with commands, verbosity levels, and fixes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ansible-skills:ansible-debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Ansible errors fall into four categories: connection, authentication, module, and syntax. Systematic diagnosis starts with identifying the category, then isolating the specific cause.
Ansible errors fall into four categories: connection, authentication, module, and syntax. Systematic diagnosis starts with identifying the category, then isolating the specific cause.
| 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 |
# 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:
# 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
# Check module documentation
ansible-doc ansible.builtin.copy
# Verify module parameters match your Ansible version
ansible --version
# Use default filter for optional variables
{{ my_var | default('fallback') }}
# Debug variable values
- ansible.builtin.debug:
var: problematic_variable
| Flag | Shows |
|---|---|
-v | Task results |
-vv | Task input parameters |
-vvv | SSH connection details |
-vvvv | Full plugin internals |
Start with -v, increase only if needed.
# 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
| 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 |
# 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
npx claudepluginhub cruftyoldsysadmin/ansible-skills --plugin ansible-skillsDebugs Ansible playbook failures including UNREACHABLE, permission denied, MODULE FAILURE, undefined variables, SSH connection issues, and sudo password errors with commands, verbosity levels, and fixes.
Provides golden rules for Ansible: uv run execution, FQCN modules, idempotency, shell best practices, sensitive task handling, and module selection guidance. Use for playbooks, tasks, ansible-playbook, or collections.
Validates syntax, lints, audits security, dry-runs with check mode, and tests with molecule Ansible playbooks, roles, inventories, FQCN, and tasks.