wait-for-it.sh: Usage, Options & Common CI Errors
wait-for-it.sh waits for a host:port to accept connections, then runs your command.
wait-for-it.sh is the popular pure-bash script for sequencing services in CI and docker-compose: block until the database port is open, then start the tests. Its sharp edges are the timeout default and what happens when the wait fails.
What it does
wait-for-it.sh polls a TCP host:port until it accepts a connection (or a timeout elapses), then optionally executes a follow-on command. It is a dependency-free bash script (uses /dev/tcp), commonly vendored into images to make a test step wait for Postgres, Redis, or an API to come up.
Common usage
./wait-for-it.sh db:5432 -- npm test
./wait-for-it.sh -t 60 db:5432 -- ./run-migrations.sh
./wait-for-it.sh localhost:8080 --strict -- echo "up"
./wait-for-it.sh redis:6379 -t 0 -- start.sh # wait forever
wait-for-it.sh api:80 -t 30 || { echo "api never came up"; exit 1; }Options
| Flag | What it does |
|---|---|
| <host>:<port> | The TCP endpoint to wait for |
| -t <secs> | Timeout (default 15; 0 = wait forever) |
| -s / --strict | Only run the command if the port came up |
| -q / --quiet | Suppress status output |
| -- <command> | Command to exec once the port is reachable |
Common errors in CI
"timeout occurred after waiting 15 seconds for db:5432" with exit 124 means the service did not come up within the default 15s - raise it with -t (DB containers often need 30-60s to be ready). Without --strict, wait-for-it runs the -- command even after a timeout, so tests start against a dead service and fail confusingly; add -s to fail fast. "wait-for-it.sh: Permission denied" / 126 - chmod +x the script. A port being open is not the same as the app being ready (e.g. Postgres accepting TCP before it accepts queries); for those, also probe with a real query or health endpoint.