testcontainers/testcontainers-java · error · IllegalStateException

Wait strategy failed. Container is removed

Error message

Wait strategy failed. Container is removed

What it means

When the wait strategy throws (typically a timeout), tryStart inspects the container to give a better diagnostic. If the container no longer exists — inspectContainerCmd throws NotFoundException or returns nothing — it throws this IllegalStateException: the container was removed (often by Ryuk or by exiting with auto-remove) while the wait strategy was waiting.

Solutions

1. Look at the earlier container logs in the test output — the container exited for a reason captured there.
2. Fix the underlying container crash (usually the 'Caused by' wait strategy timeout plus exit logs).
3. Shorten or correct the wait strategy so it matches the container's real startup behavior.
4. Check that no external cleanup (Ryuk, reaper, CI timeout) is killing containers mid-test.

Example fix

// before
container.waitingFor(Wait.forHttp("/health").forStatusCode(200)); // container dies before port ever opens
// after
container.waitingFor(Wait.forListeningPort()).withStartupTimeout(Duration.ofSeconds(60));

null

null

try {
    container.start();
} catch (ContainerLaunchException e) {
    if (e.getCause() instanceof IllegalStateException
            && e.getCause().getMessage().contains("Container is removed")) {
        // container died and was reaped — check earlier logs for the exit reason
    }
    throw e;
}

When it happens

Trigger: Container exits and is auto-removed (--rm semantics / Testcontainers cleanup) before/while the wait strategy runs; Ryuk reaper removes the container due to session termination; a resource reaper triggered mid-start.

Common situations: Wait strategy timeout far longer than container lifetime so the container dies and disappears before the check; JVM running tests with a session ID whose containers get reaped; container crashed with an image that has AutoRemove behavior.

Related errors

• Wait strategy failed. Container is dead
• 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/69172bb520764a8a. Report an issue: GitHub.

Appendix: source

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

                // Bail out, don't wait for the port to start listening.
                // (Exception thrown here will be caught below and wrapped)
                throw new IllegalStateException("Container did not start correctly.");
            }

            // 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);
                }

View on GitHub (pinned to 8e549514e3)