testcontainers/testcontainers-java · error · IllegalStateException

Wait strategy failed. Container is dead

Error message

Wait strategy failed. Container is dead

What it means

After a wait strategy failure, tryStart inspects the container state to explain why. If Docker reports the container state as 'dead', it throws this IllegalStateException with the original wait exception as cause: the container process died in a way Docker could not recover from (e.g. unclean shutdown, kernel-level kill, corrupted state).

Solutions

1. Check container logs printed before the exception for the last output of the dying process.
2. Increase memory/resources on the Docker host or CI runner.
3. Run docker events / docker inspect on a manual reproduction to see why the container went dead.
4. Verify the image runs correctly outside Testcontainers (docker run -it <image>).

Example fix

// before
new GenericContainer<>("heavy-image") // killed on 2GB CI runner
    .waitingFor(Wait.forLogMessage(".*ready.*", 1));
// after
// give the environment more memory or cap the container's own heap:
new GenericContainer<>("heavy-image")
    .withEnv("JAVA_OPTS", "-Xmx512m")
    .waitingFor(Wait.forLogMessage(".*ready.*", 1));

// ensure host has headroom:
long freeMb = ((long) ((OperatingSystemMXBean) ManagementFactory.getOperatingSystemMXBean()).getFreePhysicalMemorySize()) / 1024 / 1024;

null

try {
    container.start();
} catch (ContainerLaunchException e) {
    if (e.getCause() != null && e.getCause().getMessage().contains("Container is dead")) {
        // retry once after checking host resources
    }
    throw e;
}

When it happens

Trigger: Container's main process was killed abruptly (SIGKILL, host OOM-killer at OS level, driver problem) so inspect shows dead=true while the wait strategy was waiting; container crashed during startup with unrecoverable state.

Common situations: Containers being killed by the host for memory pressure in CI; Docker daemon issues on constrained runners; privileged-failing images that abort the process instantly. with tight memory limits killing the container host-side; corrupted image layers; Docker daemon restart mid-test.

Related errors

• Wait strategy failed. Container is removed
• Wait strategy failed. Container crashed
• Wait strategy failed. Container exited with code
• You should never close the global DockerClient!
• Check failed:

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/3a50d1a02baa33b3. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:503

            // Wait until the process within the container has become ready for use (e.g. listening on network, log message emitted, etc).
            try {
                waitUntilContainerStarted();
            } catch (Exception e) {
                logger().debug("Wait strategy threw an exception", e);
                InspectContainerResponse inspectContainerResponse = null;
                try {
                    inspectContainerResponse = dockerClient.inspectContainerCmd(containerId).exec();
                } catch (NotFoundException notFoundException) {
                    logger().debug("Container {} not found", containerId, notFoundException);
                }

                if (inspectContainerResponse == null) {
                    throw new IllegalStateException("Wait strategy failed. Container is removed", e);
                }

                InspectContainerResponse.ContainerState state = inspectContainerResponse.getState();
                if (Boolean.TRUE.equals(state.getDead())) {
                    throw new IllegalStateException("Wait strategy failed. Container is dead", e);
                }

                if (Boolean.TRUE.equals(state.getOOMKilled())) {
                    throw new IllegalStateException(
                        "Wait strategy failed. Container crashed with out-of-memory (OOMKilled)",
                        e
                    );
                }

                String error = state.getError();
                if (!StringUtils.isBlank(error)) {
                    throw new IllegalStateException("Wait strategy failed. Container crashed: " + error, e);
                }

                if (!Boolean.TRUE.equals(state.getRunning())) {
                    throw new IllegalStateException(
                        "Wait strategy failed. Container exited with code " + state.getExitCode(),
                        e

View on GitHub (pinned to 8e549514e3)