Testcontainers "Container startup failed" in CI - Fix Container Boot

Testcontainers starts a container and waits until it is "ready" per a wait strategy. "Container startup failed" means readiness was never reached in time - a slow/failed image pull, a wrong wait condition, an exhausted port, or the container crashing on boot.

What this error means

A @Testcontainers test fails with ContainerLaunchException: Container startup failed or Timed out waiting for container port to open / Wait strategy failed. The container may have pulled slowly or crashed during init.

org.testcontainers.containers.ContainerLaunchException: Container startup failed for image postgres:16
Caused by: org.testcontainers.containers.ContainerLaunchException:
Timed out waiting for container port to open (localhost ports: [49213] should be listening)

Common causes

Wait strategy or readiness timeout

The default/declared wait strategy did not match how the container signals readiness, or the container was slow to start within the timeout (sometimes transient under load).

Image pull or container crash on boot

A slow registry pull, or the container exiting on startup (bad env/config), prevents it from ever listening.

How to fix it

Use an accurate wait strategy with headroom

Wait on the real readiness signal (log line or HTTP) with a generous timeout.

var db = new GenericContainer<>("postgres:16")
    .withExposedPorts(5432)
    .waitingFor(Wait.forLogMessage(".*database system is ready to accept connections.*\\s", 2)
        .withStartupTimeout(Duration.ofSeconds(120)));

Diagnose the boot failure

1. Read the container logs Testcontainers prints on failure to see if it crashed on startup.
2. Pre-pull or pin images to avoid slow first-run pulls inside the timeout.
3. Check the env/config passed to the container is valid for that image.

How to prevent it

• Pin and pre-pull images, set readiness-accurate wait strategies with adequate timeouts, and validate container config so startup is reliable.

Related guides