{"record":{"id":"3a50d1a02baa33b3","repo":"testcontainers/testcontainers-java","slug":"wait-strategy-failed-container-is-dead","errorCode":null,"errorMessage":"Wait strategy failed. Container is dead","messagePattern":"Wait strategy failed\\. Container is dead","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":503,"sourceCode":"            // Wait until the process within the container has become ready for use (e.g. listening on network, log message emitted, etc).\n            try {\n                waitUntilContainerStarted();\n            } catch (Exception e) {\n                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","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L485-L521","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check container logs printed before the exception for the last output of the dying process.","Increase memory/resources on the Docker host or CI runner.","Run docker events / docker inspect on a manual reproduction to see why the container went dead.","Verify the image runs correctly outside Testcontainers (docker run -it <image>)."],"exampleFix":"// before\nnew GenericContainer<>(\"heavy-image\") // killed on 2GB CI runner\n    .waitingFor(Wait.forLogMessage(\".*ready.*\", 1));\n// after\n// give the environment more memory or cap the container's own heap:\nnew GenericContainer<>(\"heavy-image\")\n    .withEnv(\"JAVA_OPTS\", \"-Xmx512m\")\n    .waitingFor(Wait.forLogMessage(\".*ready.*\", 1));","handlingStrategy":"retry","validationCode":"// ensure host has headroom:\nlong freeMb = ((long) ((OperatingSystemMXBean) ManagementFactory.getOperatingSystemMXBean()).getFreePhysicalMemorySize()) / 1024 / 1024;","typeGuard":"null","tryCatchPattern":"try {\n    container.start();\n} catch (ContainerLaunchException e) {\n    if (e.getCause() != null && e.getCause().getMessage().contains(\"Container is dead\")) {\n        // retry once after checking host resources\n    }\n    throw e;\n}","preventionTips":["Monitor CI runner memory; avoid running heavy containers in parallel.","Cap in-container heap (JVM opts) below the container limit.","Validate the image runs on the target Docker driver/host."],"tags":["docker","wait-strategy","container-dead"],"backgroundTag":"container-wait-strategy-failed","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}