Diagnosing and Fixing Ansible Async Task Timeouts in Playbooks

Problem Overview

When a task in an Ansible playbook is marked failed or skipped before the remote command has a chance to finish, the most common culprit is an async configuration that is too aggressive or mis‑configured. Async tasks run in the background and return immediately, relying on a follow‑up async_status task to poll the job. If the timeout is too low, the poll will abort; if poll is set incorrectly, Ansible will check the status too soon; or if SSH pipelining is disabled, the extra round‑trips can push the job beyond the timeout on high‑latency hosts.

Common Causes

Condition	Likely Cause	Diagnostic Check	Fix
Task marked failed after a few seconds	Async timeout too low for the real workload	Check the timeout value in the playbook and the async_status output in -vvv logs	Increase timeout to a value that comfortably exceeds the expected runtime
Task marked skipped or failed immediately	Missing or zero poll value, causing Ansible to poll once and exit	Verify that poll is set to a non‑zero integer or omitted (default is 0, meaning “wait for completion”)	Set poll to a positive integer or remove the key to let Ansible wait
Async job never finishes, host remains busy	Remote host lacks required binaries or disk space, causing the job to hang	SSH into the host and run the command manually; check ps -ef | grep	Install missing dependencies, free disk space, or adjust the command to be lighter
Playbook fails on high‑latency hosts but works locally	SSH pipelining disabled, adding SSH round‑trips that trigger the timeout	Check ansible.cfg for pipelining = True and ensure ControlPersist is enabled	Enable pipelining in ansible.cfg or increase timeout
Async task shows skipped even though the command should run	Syntax error inside the async block prevents job creation	Run the playbook with -vvv and look for parsing errors before the async block	Fix the YAML syntax; ensure the async block is a proper task dictionary

Diagnostic Checklist

1. Run with Verbose Logging

   ansible-playbook site.yml -vvv

   Search for lines that start with TASK [async_task_name] => async_status. They display the timeout and poll values used.

2. Verify Async Status Output

   ansible-playbook site.yml -vvv | grep async_status

   Look for rc=0 vs rc!=0 and the finished flag.

3. Check Remote Process

   ssh user@host "ps -ef | grep $(cat /tmp/async_job_id) | grep -v grep"
   

   Replace /tmp/async_job_id with the file that Ansible writes the job ID to. If the process is still running after the timeout, the job hung.

4. Inspect SSH Configuration

   cat /etc/ansible/ansible.cfg | grep -i pipelining
   

   Ensure pipelining = True and ControlPersist is set to a reasonable value (e.g., ControlPersist=60s).

5. Confirm Remote Resources

   ssh user@host "df -h | grep /tmp"
   

   Make sure there is enough disk space for temporary files used by async jobs.

Fixes Tied to Findings

• Increase Timeout

  tasks:
    - name: Heavy computation
      shell: /usr/bin/long_task
      async: 7200
      poll: 0
  

  Set async to a value (in seconds) that exceeds the expected runtime.

• Adjust Polling Behavior

  tasks:
    - name: Run job in background
      shell: /usr/bin/long_task
      async: 3600
      poll: 30  # poll every 30 seconds
  

  A non‑zero poll keeps Ansible from marking the task failed immediately.

• Enable Pipelining

  [ssh_connection]
  pipelining = True
  ControlPersist = 60s
  

  Set in ansible.cfg or as an inventory variable. This reduces SSH round‑trips.

• Fix Syntax Errors

  tasks:
    - name: Correct async task
      shell: /usr/bin/long_task
      async: 600
      poll: 0
  

  Ensure the task dictionary is properly indented and all keys are valid.

• Resource Check

  ssh user@host "sudo apt-get install -y required_binary"
  

  Install missing binaries or free disk space before re‑running the playbook.

Escalation Criteria

If the above steps do not resolve the issue, consider:

• Running the command directly on the host to verify it completes without Ansible.
• Increasing the async timeout to a very large value and monitoring the job with ps to see if it ever exits.
• Checking Ansible logs on the controller for any SSH authentication or network errors that could be causing intermittent failures.
• Consulting the Ansible Core issue tracker for known bugs in the version you are using.

Practical Check for Success

After applying the fix, run the playbook again with -vvv and confirm that:

• The async_status task reports finished=true and rc=0.
• No skipped or failed status appears for the async task.
• On the remote host, the process terminates within the expected window.

Concrete Example

Suppose you have a playbook that runs a 30‑minute backup script asynchronously:

- hosts: db_servers
  tasks:
    - name: Start backup
      command: /usr/local/bin/backup.sh
      async: 1800  # 30 minutes
      poll: 0
      register: backup_job

    - name: Check backup status
      async_status:
        jid: "{{ backup_job.ansible_job_id }}"
      register: backup_result
      until: backup_result.finished
      retries: 60
      delay: 30

If the backup fails after 5 minutes, check that async is set to 1800. If the host is in a 200 ms latency zone, enable pipelining as described above.

Limitations

• Async tasks rely on the remote host’s ability to run background processes; if the host has restrictive security policies (e.g., noexec or SELinux enforcing), the job may be silently killed.
• Increasing timeout does not fix underlying resource starvation; it only prevents premature failure.
• SSH pipelining is not supported on all connection plugins (e.g., paramiko); it requires ssh or smart connections.

Conclusion

By systematically checking the async parameters, polling behavior, SSH configuration, and host resources, you can pinpoint why an Ansible async task is timing out or failing. The table above gives a quick reference, and the step‑by‑step checks provide a reproducible method to confirm the fix before redeploying your playbook.