{"record":{"id":"1a5e5c9eda6d5232","repo":"testcontainers/testcontainers-java","slug":"wait-strategy-failed-container-exited-with-code-exitcode","errorCode":null,"errorMessage":"Wait strategy failed. Container exited with code ${exitCode}","messagePattern":"Wait strategy failed\\. Container exited with code (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":519,"sourceCode":"                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;\n            }\n\n            logger().info(\"Container {} started in {}\", dockerImageName, Duration.between(startedAt, Instant.now()));\n            containerIsStarted(containerInfo, reused);\n        } catch (Exception e) {\n            if (e instanceof UndeclaredThrowableException && e.getCause() instanceof Exception) {\n                e = (Exception) e.getCause();\n            }\n            if (e instanceof InvocationTargetException && e.getCause() instanceof Exception) {\n                e = (Exception) e.getCause();\n            }\n            logger().error(\"Could not start container\", e);","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L501-L537","documentation":"Final fallback in tryStart's diagnostic chain: the wait strategy failed, Docker reports no error string, the container isn't dead/OOM-killed, and state.running is false — so the container simply exited. The message includes the container's exit code so you can map it to the application's own failure codes.","triggerScenarios":"Container process exits on its own during startup — application-level failure (bad config, failed DB migration, port already in use inside the container), or the main process finishes quickly because it was run as a one-off command instead of a server.","commonSituations":"Postgres failing init due to bad POSTGRES_* env values; app crashing on missing required config; using a CLI-style image as a long-running container so it exits 0 immediately and the wait times out or detects exit.","solutions":["Read the container stdout/stderr logs printed right before this exception and correlate with the exit code.","Fix the app-level startup failure (env vars, config files, ports) indicated in the logs.","If the container is a one-off command, don't wait for a server — use execInContainer or a different lifecycle.","Use a proper wait strategy matching the container's real readiness signal."],"exampleFix":"// before\nnew GenericContainer<>(\"postgres:16\"); // missing POSTGRES_PASSWORD -> exits 1\n// after\nnew GenericContainer<>(\"postgres:16\")\n    .withEnv(\"POSTGRES_PASSWORD\", \"test\")\n    .waitingFor(Wait.forLogMessage(\".*database system is ready to accept connections.*\", 2));","handlingStrategy":"try-catch","validationCode":"null","typeGuard":"null","tryCatchPattern":"try {\n    container.start();\n} catch (ContainerLaunchException e) {\n    // cause message contains 'exited with code N' — map N to the app's failure codes\n    // container stdout/stderr is printed above the stack trace\n    throw e;\n}","preventionTips":["Supply all env/config the app needs to boot (POSTGRES_PASSWORD, ports, config files).","Read the printed container logs first — they almost always name the exact failure.","Don't use one-off CLI images as long-running containers."],"tags":["docker","wait-strategy","container-exit"],"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"}