testcontainers/testcontainers-java · critical · ContainerLaunchException

Containerised Docker Compose exited abnormally with code

Error message

Containerised Docker Compose exited abnormally with code ${exitCode} whilst running command: ${commandParts}

What it means

ContainerisedDockerCompose runs docker-compose inside a helper container. After invoking the compose command it inspects the exit code; if it is null or nonzero it wraps the failure in ContainerLaunchException stating the abnormal exit code and command parts.

Solutions

Read the full stack's preceding container logs to see the underlying compose error output
Validate docker-compose.yml (e.g. docker compose config) and fix syntax/version issues
Ensure referenced images/build contexts/env files are reachable and correct
Run with ContainerisedDockerCompose/Project DockerComposeContainer debug logging (org.testcontainers DEBUG) to inspect the compose command output

Defensive patterns

Strategy: try-catch

Validate before calling

Process p = new ProcessBuilder("docker", "compose", "-f", composeFile.toString(), "config", "--quiet"); if (p.inheritIO().start().waitFor() != 0) throw new IllegalStateException("Invalid compose file: " + composeFile);

Try / catch

try { compose.start(); } catch (ContainerLaunchException e) { log.error("docker-compose failed ({}). Check compose logs above for the real error.", e.getMessage()); throw e; }

Prevention

Validate the compose file with 'docker compose config' in CI before tests
Keep images/build contexts available to the daemon
Enable org.testcontainers DEBUG logging to capture compose stdout/stderr

When it happens

Trigger: Any compose command failure: invalid docker-compose.yml, missing image/service build failure, compose file referencing nonexistent paths/images, port conflicts, or out-of-memory inside the compose container.

Common situations: Syntax errors or unsupported version key in docker-compose.yml; missing .env variables; images that fail to pull in restricted networks; build context paths not visible to the compose container.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ContainerisedDockerCompose.java:104

        followOutput(new Slf4jLogConsumer(logger()));

        // wait for the compose container to stop, which should only happen after it has spawned all the service containers
        logger().info("Docker Compose container is running for command: {}", Joiner.on(" ").join(getCommandParts()));
        while (isRunning()) {
            logger().trace("Compose container is still running");
            Uninterruptibles.sleepUninterruptibly(100, TimeUnit.MILLISECONDS);
        }

        AuditLogger.doComposeLog(getCommandParts(), getEnv());

        final Integer exitCode = getDockerClient()
            .inspectContainerCmd(getContainerId())
            .exec()
            .getState()
            .getExitCode();

        if (exitCode == null || exitCode != 0) {
            throw new ContainerLaunchException(
                "Containerised Docker Compose exited abnormally with code " +
                exitCode +
                " whilst running command: " +
                StringUtils.join(getCommandParts(), ' ')
            );
        }

        logger().info("Docker Compose has finished running");
    }

    private String convertToUnixFilesystemPath(String path) {
        return SystemUtils.IS_OS_WINDOWS ? PathUtils.createMinGWPath(path).substring(1) : path;
    }
}

View on GitHub (pinned to 8e549514e3)