LocalStack "Could not connect to LocalStack health endpoint" in CI

By Daniel Zoghalchali·Latchkey

The LocalStack health check at http://localhost:4566/_localstack/health did not answer. Either the container is still starting, or it never became healthy. Tests should wait for the health endpoint before running.

What this error means

Setup fails with "Could not connect to LocalStack health endpoint" or a connection refused to /_localstack/health, usually because tests began before LocalStack printed "Ready.".

ERROR: Could not connect to LocalStack health endpoint at http://localhost:4566/_localstack/health

Common causes

Tests started before LocalStack was ready

CI ran the test step before LocalStack finished booting, so the health endpoint was not up yet.

LocalStack failed to start on 4566

A port conflict or crash means nothing is listening on 4566, so the health check can never succeed.

How to fix it

Wait for the health endpoint before tests

Poll the health URL until it reports running, so tests only start once LocalStack is ready.

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

Confirm LocalStack actually started

1. Check the LocalStack container logs for the "Ready." line.
2. Ensure nothing else holds port 4566.
3. Only run tests after the health check passes.

How to prevent it

• Gate tests behind a health-endpoint poll, not a fixed sleep.
• Ensure port 4566 is free before starting LocalStack.
• Fail fast if LocalStack never reports ready.

Frequently asked questions

Related guides

References

• GitHub Actions documentation