testcontainers/testcontainers-java · critical · ContainerLaunchException

Error running local Docker Compose command

Error message

Error running local Docker Compose command: ${cmd}

What it means

LocalDockerCompose invokes the local `docker-compose` binary via an external process. If the process fails in any way other than a detected non-zero exit code, Testcontainers wraps the failure in a ContainerLaunchException carrying the exact command that was run. The original exception is attached as the cause.

Solutions

1. Run the same `cmd` shown in the message manually to see the underlying error (inspect the cause exception).
2. Verify Docker is running (`docker ps`) and the compose binary is on PATH (`which docker-compose`).
3. Check the compose file syntax with `docker-compose -f <file> config`.
4. On CI, ensure the Docker socket is mounted and permissions allow access.

Example fix

// before: relying on a broken environment
new LocalDockerComposeCampaign(new DockerComposeContainer<>(new File("docker-compose.yml"))).start();
// after: pre-check the environment before starting
new ProcessBuilder("docker-compose", "version").start().waitFor(); // fails fast with a clear message if binary missing

new ProcessBuilder("docker-compose", "version").inheritIO().start().waitFor() == 0; // also check `docker info`

try { composeContainer.start(); } catch (ContainerLaunchException e) { logger.error("docker-compose failed: {}", e.getCause(), e); throw new EnvironmentPreconditionException(e); }

When it happens

Trigger: invoke() runs `docker-compose ... up` as a shell command and any Exception other than the specific ShutdownException for abnormal exit codes (e.g. docker-compose binary missing, Docker daemon not reachable, compose file invalid in a way the CLI crashes on) triggers this throw.

Common situations: Docker daemon not running, `docker-compose`/`docker compose` not installed or not on PATH, malformed compose file passed to LocalDockerComposeCampaign, environment misconfiguration on CI agents.

Related errors

• Containerised Docker Compose exited abnormally with code
• Services named do not exist, but wait conditions have been…
• Could not get a port for
• Local Docker Compose not found. Is
• Local Docker Compose exited abnormally with code

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/LocalDockerCompose.java:124

            new ProcessExecutor()
                .command(command)
                .redirectOutput(Slf4jStream.of(logger()).asInfo())
                .redirectError(Slf4jStream.of(logger()).asInfo()) // docker-compose will log pull information to stderr
                .environment(environment)
                .directory(pwd)
                .exitValueNormal()
                .executeNoTimeout();

            logger().info("Docker Compose has finished running");
        } catch (InvalidExitValueException e) {
            throw new ContainerLaunchException(
                "Local Docker Compose exited abnormally with code " +
                e.getExitValue() +
                " whilst running command: " +
                cmd
            );
        } catch (Exception e) {
            throw new ContainerLaunchException("Error running local Docker Compose command: " + cmd, e);
        }
    }

    /**
     * @return a logger
     */
    private Logger logger() {
        return DockerLoggerFactory.getLogger(this.composeExecutable);
    }
}

View on GitHub (pinned to 8e549514e3)