testcontainers/testcontainers-java · error · IllegalStateException

Wait strategy failed. Container crashed with out-of-memory…

Error message

Wait strategy failed. Container crashed with out-of-memory (OOMKilled)

What it means

After wait strategy failure, tryStart checks Docker's OOMKilled flag. If true it throws this IllegalStateException: the kernel killed the container's process because it exceeded its memory limit (or the host ran out of memory). The original wait-strategy exception is the cause.

Solutions

1. Increase the container memory limit or remove it: withCreateContainerCmdModifier(cmd -> cmd.getHostConfig().withMemory(...)).
2. Reduce the in-container app's memory (e.g. JVM -Xmx, ES ES_JAVA_OPTS, Kafka KAFKA_HEAP_OPTS).
3. Free host memory / run fewer containers in parallel in CI.
4. Check docker inspect <container> for state.OOMKilled to confirm after reproduction.

Example fix

// before
new GenericContainer<>(DockerImageName.parse("elasticsearch:8.11.0")); // needs ~2GB, CI has 1GB
// after
new GenericContainer<>(DockerImageName.parse("elasticsearch:8.11.0"))
    .withEnv("ES_JAVA_OPTS", "-Xms512m -Xmx512m");

// set an explicit memory limit the app can live with:
container.getCreateCommandModifier() // or at construction:
container.withCreateContainerCmdModifier(cmd ->
    cmd.getHostConfig().withMemory(1024L * 1024 * 1024));

null

try {
    container.start();
} catch (ContainerLaunchException e) {
    if (e.getCause() != null && e.getCause().getMessage().contains("OOMKilled")) {
        // raise memory limit or lower app heap, then retry
    }
    throw e;
}

When it happens

Trigger: Container memory usage exceeds the limit set via withCreateContainerCmdModifier (HostConfig memory) or the host/CI runner is memory-starved during startup; JVM inside the container allocating more than the container limit.

Common situations: Kafka/Elasticsearch/Postgres containers with default heavy memory settings on small CI runners; setting a HostConfig memory limit lower than the app's needs; running many containers in parallel during a test suite.

Related errors

• An error occurred
• An error occurred
• Can not connect to Ryuk at
• Can't close DockerClient
• Can't parse the default gateway IP

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

Appendix: source

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

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

                throw e;

View on GitHub (pinned to 8e549514e3)