testcontainers/testcontainers-java · critical · ContainerLaunchException

Local Docker Compose not found. Is

Error message

Local Docker Compose not found. Is ${composeExecutable} on the PATH?

What it means

Thrown by LocalDockerCompose.invoke() as a ContainerLaunchException when the configured docker-compose executable (default "docker-compose") cannot be found on the system PATH before running compose. TestContainers checks existence up front (CommandLine.executableExists) and bails out early because it cannot run local docker compose without the binary.

Solutions

1. Install docker-compose and ensure it is on the PATH used by the test JVM (`docker-compose --version` must work).
2. If you only have the Compose v2 plugin, use a TestContainers version supporting `docker compose`, or expose a shim named on PATH (e.g. create /usr/local/bin/docker-compose wrapping `docker compose "$@"`).
3. Set the custom executable correctly: new DockerComposeContainer(env, identifier, "/path/to/compose") with an absolute path to the binary.
4. Fix PATH in CI/IDE run configurations so the test JVM inherits the directory containing docker-compose.

Example fix

// before: fails when only the v2 plugin exists
new DockerComposeContainer(new File("docker-compose.yml"));

// after: point at an existing compose binary/plugin shim
new DockerComposeContainer(new File("docker-compose.yml"))
    .withLocalCompose(true); // after installing docker-compose on PATH

// Run before starting DockerComposeContainer
Process p = new ProcessBuilder("docker-compose", "--version").redirectErrorStream(true);
try {
    if (p.start().waitFor() != 0) throw new IllegalStateException("docker-compose not usable on PATH");
} catch (java.io.IOException e) {
    throw new IllegalStateException("docker-compose not found on PATH", e);
}

try {
    composeContainer.start();
} catch (ContainerLaunchException e) {
    if (e.getMessage().contains("not found")) {
        throw new IllegalStateException("Install docker-compose and add it to PATH", e);
    }
    throw e;
}

When it happens

Trigger: Using DockerComposeContainer / LocalDockerCompose when docker-compose (or the configured composeExecutable) is not installed, not on PATH, or was overridden via a custom executable name that does not exist in the test environment.

Common situations: CI images that install only the Docker daemon but not docker-compose; devs who use `docker compose` (v2 plugin, no standalone binary) while the library default expects a standalone `docker-compose` binary; custom PATH in IDE/Gradle test runners that differs from the shell PATH.

Related errors

• Local Docker Compose exited abnormally with code
• You should never close the global DockerClient!
• Check failed:
• Services named do not exist, but wait conditions have been…
• Could not get a port for

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

Appendix: source

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

    }

    @Override
    public DockerCompose withCommand(String cmd) {
        this.cmd = cmd;
        return this;
    }

    @Override
    public DockerCompose withEnv(Map<String, String> env) {
        this.env = env;
        return this;
    }

    @Override
    public void invoke() {
        // bail out early
        if (!CommandLine.executableExists(this.composeExecutable)) {
            throw new ContainerLaunchException(
                "Local Docker Compose not found. Is " + this.composeExecutable + " on the PATH?"
            );
        }

        final Map<String, String> environment = Maps.newHashMap(env);
        environment.put(ENV_PROJECT_NAME, identifier);

        TransportConfig transportConfig = DockerClientFactory.instance().getTransportConfig();
        SSLConfig sslConfig = transportConfig.getSslConfig();
        if (sslConfig != null) {
            if (sslConfig instanceof LocalDirectorySSLConfig) {
                environment.put("DOCKER_CERT_PATH", ((LocalDirectorySSLConfig) sslConfig).getDockerCertPath());
                environment.put("DOCKER_TLS_VERIFY", "true");
            } else {
                logger()
                    .warn(
                        "Couldn't set DOCKER_CERT_PATH. `sslConfig` is present but it's not LocalDirectorySSLConfig."
                    );

View on GitHub (pinned to 8e549514e3)