{"record":{"id":"f608b70a09329ea9","repo":"testcontainers/testcontainers-java","slug":"container-did-not-start-correctly","errorCode":null,"errorMessage":"Container did not start correctly.","messagePattern":"Container did not start correctly\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":482,"sourceCode":"                                .collect(Collectors.toSet());\n\n                            return exposedAndMappedPorts.containsAll(this.containerDef.getExposedPorts());\n                        }\n                    );\n\n            String emulationWarning = checkForEmulation();\n            if (emulationWarning != null) {\n                logger().warn(emulationWarning);\n            }\n\n            // Tell subclasses that we're starting\n            containerIsStarting(containerInfo, reused);\n\n            // Wait until the container has reached the desired running state\n            if (!this.startupCheckStrategy.waitUntilStartupSuccessful(this)) {\n                // Bail out, don't wait for the port to start listening.\n                // (Exception thrown here will be caught below and wrapped)\n                throw new IllegalStateException(\"Container did not start correctly.\");\n            }\n\n            // 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","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L464-L500","documentation":"Thrown by tryStart when the startupCheckStrategy (default: wait until the container's main process is running) reports the container never reached a successful startup state. This is raised before wait strategies run, meaning the container was created and started but immediately failed to stay up — it's then wrapped by the ContainerLaunchException from doStart.","triggerScenarios":"The container's entrypoint/command exits immediately (bad command, missing script, invalid flags), the image's default CMD fails, or the container is killed right after start so waitUntilStartupSuccessful returns false.","commonSituations":"Wrong command passed via withCommand(); image requiring environment variables that aren't set; entrypoint referencing a file not present in the image; container exiting with a non-zero code within milliseconds of starting.","solutions":["Read the container logs printed by Testcontainers (stdout/stderr before the exception) to see why the process exited.","Fix the command/entrypoint: container.withCommand(\"correct-command\") or use a proper image.","Add required env/config with withEnv()/withFileSystemBind() so the process can start.","Run the image manually (docker run <image> <cmd>) to reproduce and debug the immediate exit."],"exampleFix":"// before\nnew GenericContainer<>(\"myimage\").withCommand(\"/opt/run.sh\"); // script missing -> instant exit\n// after\nnew GenericContainer<>(\"myimage\").withCommand(\"java\", \"-jar\", \"app.jar\");","handlingStrategy":"validation","validationCode":"// reproduce the exact command locally before running tests:\n// docker run --rm <image> <cmd>  -> must stay running, not exit immediately","typeGuard":"null","tryCatchPattern":"try {\n    container.start();\n} catch (ContainerLaunchException e) {\n    // container logs were printed above — check them for the immediate exit reason\n    throw e;\n}","preventionTips":["Verify image+command manually with docker run before wiring into tests.","Provide all required env vars and mounts the image needs.","Keep the main process in the foreground (no backgrounded daemons that exit)."],"tags":["docker","container-startup","startup-check"],"backgroundTag":"container-startup-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"}