testcontainers/testcontainers-java · error · IllegalStateException

Container did not start correctly.

Error message

Container did not start correctly.

What it means

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.

Solutions

1. Read the container logs printed by Testcontainers (stdout/stderr before the exception) to see why the process exited.
2. Fix the command/entrypoint: container.withCommand("correct-command") or use a proper image.
3. Add required env/config with withEnv()/withFileSystemBind() so the process can start.
4. Run the image manually (docker run <image> <cmd>) to reproduce and debug the immediate exit.

Example fix

// before
new GenericContainer<>("myimage").withCommand("/opt/run.sh"); // script missing -> instant exit
// after
new GenericContainer<>("myimage").withCommand("java", "-jar", "app.jar");

// reproduce the exact command locally before running tests:
// docker run --rm <image> <cmd>  -> must stay running, not exit immediately

null

try {
    container.start();
} catch (ContainerLaunchException e) {
    // container logs were printed above — check them for the immediate exit reason
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Container startup failed for image
• Could not create/start container
• You should never close the global DockerClient!
• Check failed:
• Requested port ( ) is not mapped

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

Appendix: source

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

                                .collect(Collectors.toSet());

                            return exposedAndMappedPorts.containsAll(this.containerDef.getExposedPorts());
                        }
                    );

            String emulationWarning = checkForEmulation();
            if (emulationWarning != null) {
                logger().warn(emulationWarning);
            }

            // Tell subclasses that we're starting
            containerIsStarting(containerInfo, reused);

            // Wait until the container has reached the desired running state
            if (!this.startupCheckStrategy.waitUntilStartupSuccessful(this)) {
                // Bail out, don't wait for the port to start listening.
                // (Exception thrown here will be caught below and wrapped)
                throw new IllegalStateException("Container did not start correctly.");
            }

            // Wait until the process within the container has become ready for use (e.g. listening on network, log message emitted, etc).
            try {
                waitUntilContainerStarted();
            } catch (Exception e) {
                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);
                }

View on GitHub (pinned to 8e549514e3)