Testcontainers "Wait strategy failed" in CI

By Daniel Zoghalchali·Latchkey

A wait-strategy failure means the readiness probe hit an error condition: the container stopped while waiting, the HTTP path returned an unexpected status, or the mapped port never appeared. The wrapped cause tells you which.

What this error means

Setup fails with "Wait strategy failed for container" and a nested cause such as a closed connection, an unexpected HTTP status, or the container no longer running.

org.testcontainers.containers.ContainerLaunchException: Wait strategy failed for container
Caused by: org.rnorth.ducttape.TimeoutException: Timeout waiting for result with exception

Common causes

The probe targets a wrong port or path

An HTTP wait on a path that returns 404, or a port wait on a port the app does not expose, makes the strategy fail rather than pass.

The container stopped while the probe ran

If the app crashes mid-startup, the readiness probe fails because the container is no longer running.

How to fix it

Align the probe with the app

1. Confirm the exposed port and health path match what the app actually serves.
2. Use forHttp with the correct path and expected status.
3. Check container logs to rule out a crash before blaming the probe.

.waitingFor(Wait.forHttp("/actuator/health").forStatusCode(200))

Wait for a specific log line when no endpoint exists

For services without a health endpoint, wait for a known startup log message emitted once the service is ready.

.waitingFor(Wait.forLogMessage(".*Ready to accept connections.*", 1))

How to prevent it

• Match the wait strategy exactly to the container port and readiness path.
• Prefer log or HTTP readiness over bare port checks for accuracy.
• Inspect container logs when a probe fails to distinguish crash from misconfig.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation