🚨 Ansible Error: 'Timeout when waiting for ...' (wait_for) — Cause, Fix, and Troubleshooting Guide

Overview

The wait_for module blocks until a condition is met — a port opens, a file appears, or a string shows up in a file — then returns. If the condition is not met within timeout seconds (default 300), it fails:

fatal: [web-01]: FAILED! => {"changed": false, "elapsed": 300, "msg": "Timeout when waiting for 127.0.0.1:8080"}

Or for a search string:

fatal: [web-01]: FAILED! => {"msg": "Timeout when waiting for search string Ready in /var/log/app.log"}

The module did its job; the thing it waited for never happened in time.

Symptoms

• A wait_for task fails after a long pause (often exactly the timeout).
• The service it waits on actually did (or did not) start — the port/string check disagrees.
• Passes on a fast host, times out on a slow/loaded one.

ansible-playbook -i inventory.ini deploy.yml

TASK [Wait for app port] ******
fatal: [web-01]: FAILED! => {"elapsed": 300, "msg": "Timeout when waiting for 127.0.0.1:8080"}

Common Root Causes

1. The service failed to start

The app crashed or exited, so nothing ever listens on the port / writes the string.

2. Wrong host or port

Waiting on 127.0.0.1 when the service binds to a specific interface, or the wrong port entirely.

3. Firewall / binding on a different interface

The port is open but not reachable from where wait_for checks (localhost vs external).

4. Timeout too short for a slow start

DB migrations or JIT warmup take longer than the default; the check gives up early.

5. Search string never matches

A typo or a log format change means the expected string never appears.

How to diagnose

Check whether anything is actually listening:

ansible web-01 -i inventory.ini -m shell -a 'ss -ltnp | grep :8080 || echo "nothing on 8080"'

Inspect the service and logs:

ansible web-01 -i inventory.ini -b -m shell -a 'systemctl status app --no-pager; tail -n 20 /var/log/app.log'

Fixes

Wait on the correct host/port and a sane timeout

- name: Wait for app to accept connections
  ansible.builtin.wait_for:
    host: 0.0.0.0
    port: 8080
    state: started
    timeout: 120
    delay: 5

Wait for a readiness string in the log

- name: Wait until app reports ready
  ansible.builtin.wait_for:
    path: /var/log/app.log
    search_regex: "Application started|Ready to accept"
    timeout: 180

Prefer an application health check

wait_for only proves the socket is open; use uri to confirm real readiness:

- name: Wait for healthy endpoint
  ansible.builtin.uri:
    url: http://127.0.0.1:8080/health
    status_code: 200
  register: health
  retries: 30
  delay: 5
  until: health.status == 200

Make sure the service actually started first

- name: Ensure app is running
  ansible.builtin.service:
    name: app
    state: started

What to watch out for

• wait_for port passing only means the TCP port is open — the app may still be returning errors; a uri health check is stronger.
• Binding matters: waiting on 127.0.0.1 fails if the app binds to a specific LAN IP, and vice versa.
• Set delay so the check does not start before the service has had a moment to spawn, avoiding a false early failure.

Related

• Ansible Error: ‘Failed, retrying … retries exhausted’
• Making Flaky Ansible Tasks Reliable With AI: retry, until, wait_for
• Ansible Error: ‘UNREACHABLE! Failed to connect to the host via ssh’