LocalStack "Ready." wait race (tests run too early) in CI

By Kaveh Alemi·Latchkey

LocalStack prints "Ready." to its logs once it can serve requests. Jobs that use a fixed sleep instead of waiting for that signal race the boot: on a slow runner the sleep ends first and the first AWS call fails.

What this error means

The first AWS calls fail intermittently right after startup, and adding time makes it pass, because a fixed sleep sometimes ends before LocalStack is actually ready.

# fixed sleep beats readiness on a slow runner:
sleep 5
aws --endpoint-url=http://localhost:4566 s3 ls
# Could not connect to the endpoint URL: "http://localhost:4566/"

Common causes

A fixed sleep replaced a real readiness check

A hardcoded sleep cannot know when LocalStack is ready; on slow runners it finishes before boot completes.

No wait on the health endpoint or Ready log

Without polling the health endpoint or the "Ready." log line, tests start on a guess.

How to fix it

Poll the health endpoint until ready

Replace the fixed sleep with a loop that waits for the health endpoint to report running.

until curl -sf http://localhost:4566/_localstack/health >/dev/null; do sleep 2; done

Wait for the "Ready." log line

When using a service container, wait until LocalStack logs "Ready." before starting tests.

docker logs localstack 2>&1 | grep -q "Ready." || sleep 2

How to prevent it

• Replace fixed sleeps with a health-endpoint or Ready-log poll.
• Add a bounded retry so slow runners still pass deterministically.
• Treat readiness as a signal to wait on, not a duration to guess.

Frequently asked questions

Related guides

References

• GitHub Actions documentation