autojanet/skills/ansible-debug/SKILL.md
Zoë cc74ad0bd0
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
fix: use library/ Harbor project, add skills, fix pipeline secrets
- .woodpecker.yaml: image paths -> library/autojanet-{agent,dispatcher}
- .woodpecker.yaml: secret names RS_HARBOR_USER / RS_HARBOR_PASS (global)
- container/Dockerfile: restore COPY skills/, skills/ populated from opencode config
- skills/: 84 opencode skills bundled into image
- k8s/manifests: update image refs to library/
2026-05-30 15:43:14 -07:00

3.3 KiB

name description
ansible-debug Use when playbooks fail with UNREACHABLE, permission denied, MODULE FAILURE, or undefined variable errors. Use when SSH connections fail or sudo password is missing.

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