{"record":{"id":"285a4b2c96497673","repo":"testcontainers/testcontainers-java","slug":"wait-strategy-failed-container-crashed-with-out-of-memory","errorCode":null,"errorMessage":"Wait strategy failed. Container crashed with out-of-memory (OOMKilled)","messagePattern":"Wait strategy failed\\. Container crashed with out-of-memory \\(OOMKilled\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":507,"sourceCode":"                logger().debug(\"Wait strategy threw an exception\", e);\n                InspectContainerResponse inspectContainerResponse = null;\n                try {\n                    inspectContainerResponse = dockerClient.inspectContainerCmd(containerId).exec();\n                } catch (NotFoundException notFoundException) {\n                    logger().debug(\"Container {} not found\", containerId, notFoundException);\n                }\n\n                if (inspectContainerResponse == null) {\n                    throw new IllegalStateException(\"Wait strategy failed. Container is removed\", e);\n                }\n\n                InspectContainerResponse.ContainerState state = inspectContainerResponse.getState();\n                if (Boolean.TRUE.equals(state.getDead())) {\n                    throw new IllegalStateException(\"Wait strategy failed. Container is dead\", e);\n                }\n\n                if (Boolean.TRUE.equals(state.getOOMKilled())) {\n                    throw new IllegalStateException(\n                        \"Wait strategy failed. Container crashed with out-of-memory (OOMKilled)\",\n                        e\n                    );\n                }\n\n                String error = state.getError();\n                if (!StringUtils.isBlank(error)) {\n                    throw new IllegalStateException(\"Wait strategy failed. Container crashed: \" + error, e);\n                }\n\n                if (!Boolean.TRUE.equals(state.getRunning())) {\n                    throw new IllegalStateException(\n                        \"Wait strategy failed. Container exited with code \" + state.getExitCode(),\n                        e\n                    );\n                }\n\n                throw e;","sourceCodeStart":489,"sourceCodeEnd":525,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L489-L525","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the container memory limit or remove it: withCreateContainerCmdModifier(cmd -> cmd.getHostConfig().withMemory(...)).","Reduce the in-container app's memory (e.g. JVM -Xmx, ES ES_JAVA_OPTS, Kafka KAFKA_HEAP_OPTS).","Free host memory / run fewer containers in parallel in CI.","Check docker inspect <container> for state.OOMKilled to confirm after reproduction."],"exampleFix":"// before\nnew GenericContainer<>(DockerImageName.parse(\"elasticsearch:8.11.0\")); // needs ~2GB, CI has 1GB\n// after\nnew GenericContainer<>(DockerImageName.parse(\"elasticsearch:8.11.0\"))\n    .withEnv(\"ES_JAVA_OPTS\", \"-Xms512m -Xmx512m\");","handlingStrategy":"validation","validationCode":"// set an explicit memory limit the app can live with:\ncontainer.getCreateCommandModifier() // or at construction:\ncontainer.withCreateContainerCmdModifier(cmd ->\n    cmd.getHostConfig().withMemory(1024L * 1024 * 1024));","typeGuard":"null","tryCatchPattern":"try {\n    container.start();\n} catch (ContainerLaunchException e) {\n    if (e.getCause() != null && e.getCause().getMessage().contains(\"OOMKilled\")) {\n        // raise memory limit or lower app heap, then retry\n    }\n    throw e;\n}","preventionTips":["Configure in-container memory (JVM -Xmx, ES/Kafka heap opts) below the container limit.","Budget host memory: sum of all container limits < runner RAM.","Prefer explicit HostConfig memory limits over relying on host defaults."],"tags":["docker","oom","memory-limit"],"backgroundTag":"container-oom-killed","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}