You're running a playbook and suddenly see FAILED! => {"changed": false, "msg": "..."} with a module-specific error. Module failures are frustrating because the error message varies significantly depending on which module failed and why. The key to solving these errors is understanding what the module was trying to do and why it couldn't complete the task.

Understanding Module Failures

Ansible modules are Python scripts that execute on target hosts. When a module fails, it means the script encountered an error while trying to perform its specific function. Common causes include missing dependencies, insufficient permissions, incorrect parameters, or unexpected system states.

Diagnosis Commands

Start with verbose output to see the full error:

```bash # Run playbook with verbose output ansible-playbook site.yml -vvv

# For specific task debugging ansible-playbook site.yml --start-at-task="task_name" -vvv ```

Check if the module exists and is properly named:

```bash # List all available modules ansible-doc -l | grep module_name

# Get detailed documentation for a specific module ansible-doc module_name ```

Test the module directly:

```bash # Run a module with ad-hoc command ansible target-host -m module_name -a "param1=value1 param2=value2" -vvv

# Example: test the yum module ansible target-host -m yum -a "name=nginx state=present" ```

Check Python and dependencies on the target host:

```bash # Check Python version ansible target-host -a "python3 --version"

# Check if required Python libraries are installed ansible target-host -m pip -a "name=requests state=present" ```

Common Solutions

Solution 1: Fix Missing Python Dependencies

Many modules require specific Python libraries. For example, the docker_container module requires Docker SDK:

```bash # Install required Python packages pip install docker

# Or use pip module in playbook - name: Install Docker SDK for Python pip: name: docker state: present ```

For yum module issues:

bash
# Ensure yum-utils is installed
ansible target-host -m yum -a "name=yum-utils state=present"

For apt module issues:

bash
# Update apt cache first
ansible target-host -m apt -a "update_cache=yes"

Solution 2: Fix Permission Issues

Modules may fail due to insufficient privileges:

yaml
- name: Task requiring elevated privileges
  yum:
    name: nginx
    state: present
  become: yes
  become_method: sudo

Ensure the user has sudo privileges without password:

```bash # On target host, edit sudoers sudo visudo

# Add line for passwordless sudo ansible-user ALL=(ALL) NOPASSWD: ALL ```

Solution 3: Fix Parameter Validation Errors

Many modules require specific parameter formats:

```yaml # Incorrect: using deprecated syntax - name: Install package (old syntax) yum: pkg: nginx state: installed

# Correct: using current syntax - name: Install package (current syntax) yum: name: nginx state: present ```

Check module documentation for parameter requirements:

bash
ansible-doc module_name

Solution 4: Fix Python Interpreter Issues

If Ansible can't find the correct Python interpreter:

```yaml # In playbook - hosts: all vars: ansible_python_interpreter: /usr/bin/python3

# Or in inventory [target_servers] target-host ansible_python_interpreter=/usr/bin/python3 ```

Solution 5: Fix SELinux/AppArmor Restrictions

On systems with SELinux enforcing, certain operations may be blocked:

```bash # Check SELinux status ansible target-host -a "getenforce"

# Temporarily set to permissive for testing ansible target-host -b -m selinux -a "policy=targeted state=permissive"

# For persistent changes ansible target-host -b -m selinux -a "policy=targeted state=enforcing" ```

Solution 6: Handle Race Conditions and Timeouts

For long-running operations:

yaml
- name: Download large file
  get_url:
    url: http://example.com/large-file.tar.gz
    dest: /tmp/large-file.tar.gz
    timeout: 300

For services that take time to start:

yaml
- name: Start service and wait
  service:
    name: myservice
    state: started
  async: 45
  poll: 5

Verification

After applying fixes, verify the module works:

```bash # Test the specific module that was failing ansible target-host -m module_name -a "parameters"

# Run the full playbook ansible-playbook site.yml --check

# Execute the playbook ansible-playbook site.yml ```

Debugging Techniques

Use the debug module to inspect variables:

yaml
- name: Debug variable
  debug:
    var: my_variable
    verbosity: 2

Use register to capture output:

```yaml - name: Run command command: some_command register: output

  • name: Show output
  • debug:
  • var: output
  • `

Add error handling for better messages:

```yaml - name: Task that might fail module_name: param: value register: result ignore_errors: yes

  • name: Show error if failed
  • debug:
  • msg: "Task failed: {{ result.msg }}"
  • when: result is failed
  • `

Module failures are often specific to the module in question, so always consult ansible-doc module_name for the exact parameter requirements and common issues. The verbose output with -vvv is your best friend for understanding exactly what went wrong.