My wait-for-it wrapper reported success for a port that never opened

I had the usual line in an entrypoint script:

./wait-for-it.sh db:5432 -- python app.py

The container exited 0. Then the application died three seconds later with
connection refused, and I spent an afternoon blaming the database image.

The database never came up. wait-for-it.sh knew that. It printed its timeout
warning, and then it ran my command anyway, and the exit code I checked was the
exit code of python app.py starting up successfully — which it did, for about
three seconds.

I want to be precise about what is a bug and what is a design decision. This one
is a design decision, it is documented, and it bit me anyway because the
documented behaviour is the opposite of what the name of the tool promises.

What the script actually does at the end

The repo is https://github.com/Raknaos/wait-for-it — a revived copy of
vishnubob's original, MIT licensed, upstream history preserved. The whole tool is
one file of 182 lines of bash. Here is its final block, verbatim:

if [[ $WAITFORIT_CLI != "" ]]; then
    if [[ $WAITFORIT_RESULT -ne 0 && $WAITFORIT_STRICT -eq 1 ]]; then
        echoerr "$WAITFORIT_cmdname: strict mode, refusing to execute subprocess"
        exit $WAITFORIT_RESULT
    fi
    exec "${WAITFORIT_CLI[@]}"
else
    exit $WAITFORIT_RESULT
fi

Read the condition again. Refusing to run the command requires both a failed
wait and -s. Without -s, a failed wait falls through to exec. And
because it is exec, the script's own exit status is replaced by the child's, so
the timeout leaves no trace in the return code at all.

I ran it on my machine today to have the numbers instead of my memory:

$ ./wait-for-it.sh 127.0.0.1:1 -t 5
wait-for-it.sh: waiting 5 seconds for 127.0.0.1:1
wait-for-it.sh: timeout occurred after waiting 5 seconds for 127.0.0.1:1
$ echo $?
124

$ ./wait-for-it.sh 127.0.0.1:1 -t 2 -- echo "RAN ANYWAY"
wait-for-it.sh: waiting 2 seconds for 127.0.0.1:1
wait-for-it.sh: timeout occurred after waiting 2 seconds for 127.0.0.1:1
RAN ANYWAY
$ echo $?
0

That second run is the entire story. Nothing opened on port 1, the script said so
out loud, and the process still reported success. Exit 124 is the coreutils
timeout status leaking through — the script re-invokes itself under timeout
so that Ctrl-C works during a wait, which is a genuinely clever piece of bash and
is why you see 124 rather than 1.

So the rule is: wait-for-it.sh without -s is not a check. It is a delay with
a ceiling. If you want a gate, the flag is not optional.

Why I picked up the repo instead of rewriting it

Because the probe itself is the interesting part and a rewrite would have lost it:

if [[ $WAITFORIT_ISBUSY -eq 1 ]]; then
    nc -z $WAITFORIT_HOST $WAITFORIT_PORT
    WAITFORIT_result=$?
else
    (echo -n > /dev/tcp/$WAITFORIT_HOST/$WAITFORIT_PORT) >/dev/null 2>&1
    WAITFORIT_result=$?
fi

/dev/tcp is a bash pseudo-device, not a file. It opens a TCP connection with no
binary to install, which is why this works in a scratch container that has bash
and nothing else — no netcat, no curl, no Python. The ISBUSY branch exists
because Alpine ships busybox, whose timeout does not always accept the same
flags, so the script resolves its own timeout through realpath and checks the
path for the string busybox. Two environment differences, handled with four
lines. That is the whole argument for pure bash here.

What the revival changes is the test situation. Upstream ships a test/
directory: wait-for-it.py, container-runners.py and a requirements.txt
pinning docker>=4.0.0 and parameterized>=0.7.0. The runners spin up four base
images — two Debian-python tags and two Alpine/busybox combinations — to exercise
the busybox branch. In a repo whose whole point is "no dependencies outside the
shell", a test suite that needs Docker and two pip packages is a strange fit. The
revived repo drops that directory and replaces it with test_wait_for_it.py at
the root: 47 lines, stdlib only, two tests. The first binds an ephemeral loopback
port, runs wait-for-it.sh against it and asserts exit 0 plus the child
command's output. The second opens a socket to reserve a port, closes it, and
asserts a non-zero exit — under --strict.

The script itself is untouched: wait-for-it.sh in this repo is byte-identical to
upstream's, all 182 lines. That is deliberate.

And that last detail about the suite is the one I keep turning over. The only
failure case it asserts is the strict one. The default, non-strict,
run-the-command-anywhere path is untested — not because someone forgot, but
because as far as the script is concerned it is not a failure path. I left it
that way. Covering it would mean asserting that a timed-out wait still runs your
command, which freezes the behaviour that surprised me into a contract.

What it costs, and what it will not tell you

Being honest about the sharp edges I hit while measuring:

One second, minimum. The loop ends in sleep 1. A service that is ready 200 ms
after a probe still waits 800 ms. On a laptop, fine. In front of a docker-compose
up that gates a whole dependency graph, you pay it once per dependency.

A name that cannot resolve looks exactly like a port that is closed. I pointed
it at no-such-host-raknaos-test.invalid:80 with -t 3. Output:
timeout occurred after waiting 3 seconds. Exit 124. No hint that DNS was the
problem. The probe discards bash's error text into /dev/null, so a typo in your
service name and a database still booting are the same event.

Service names in the port field do not work. 127.0.0.1:http — where /etc/services
says port 80 — also just times out. The port goes into /dev/tcp as written.

IPv6 literals are mangled, silently. This is the one I would call a defect:

$ ./wait-for-it.sh ::1:80 -t 2
wait-for-it.sh: waiting 2 seconds for 1:80

Argument parsing matches *:* and splits on :, so ::1:80 does not survive the
trip: the host became 1. The script then waits for a host named 1 for as long
as you let it. On a dual-stack network where your database only has an AAAA
record, this fails in the least helpful way available.

The default timeout is 15 seconds and it is not announced until it fires.
WAITFORIT_TIMEOUT=${WAITFORIT_TIMEOUT:-15}. Run without -t on a closed port and
you wait a quarter of a minute, which is short enough to look like the script
succeeded and long enough to hide inside a slow build.

Use it, with the flag

git clone https://github.com/Raknaos/wait-for-it
cd wait-for-it && python3 test_wait_for_it.py

ALL TESTS PASSED on my machine, no dependencies beyond Python and bash. Then put
-s in your entrypoint and decide what you want to happen when the dependency
loses the race:

./wait-for-it.sh db:5432 --strict -t 60 -- python app.py

Now a dead database stops the container at the gate with exit 124 instead of
starting an application that has nothing to talk to. If your orchestrator treats
a non-zero exit as "restart me", the restart loop is what you wanted in the first
place. The tool is 182 lines of bash, and the whole lesson fits in one flag, which
is why it took me a wasted afternoon to learn it.