{"record":{"id":"1d6573422c16613e","repo":"testcontainers/testcontainers-java","slug":"local-docker-compose-not-found-is-composeexecutable-on-the","errorCode":null,"errorMessage":"Local Docker Compose not found. Is ${composeExecutable} on the PATH?","messagePattern":"Local Docker Compose not found\\. Is (.+?) on the PATH\\?","errorType":"exception","errorClass":"ContainerLaunchException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/testcontainers/containers/LocalDockerCompose.java","lineNumber":61,"sourceCode":"    }\n\n    @Override\n    public DockerCompose withCommand(String cmd) {\n        this.cmd = cmd;\n        return this;\n    }\n\n    @Override\n    public DockerCompose withEnv(Map<String, String> env) {\n        this.env = env;\n        return this;\n    }\n\n    @Override\n    public void invoke() {\n        // bail out early\n        if (!CommandLine.executableExists(this.composeExecutable)) {\n            throw new ContainerLaunchException(\n                \"Local Docker Compose not found. Is \" + this.composeExecutable + \" on the PATH?\"\n            );\n        }\n\n        final Map<String, String> environment = Maps.newHashMap(env);\n        environment.put(ENV_PROJECT_NAME, identifier);\n\n        TransportConfig transportConfig = DockerClientFactory.instance().getTransportConfig();\n        SSLConfig sslConfig = transportConfig.getSslConfig();\n        if (sslConfig != null) {\n            if (sslConfig instanceof LocalDirectorySSLConfig) {\n                environment.put(\"DOCKER_CERT_PATH\", ((LocalDirectorySSLConfig) sslConfig).getDockerCertPath());\n                environment.put(\"DOCKER_TLS_VERIFY\", \"true\");\n            } else {\n                logger()\n                    .warn(\n                        \"Couldn't set DOCKER_CERT_PATH. `sslConfig` is present but it's not LocalDirectorySSLConfig.\"\n                    );","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/LocalDockerCompose.java#L43-L79","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install docker-compose and ensure it is on the PATH used by the test JVM (`docker-compose --version` must work).","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 \"$@\"`).","Set the custom executable correctly: new DockerComposeContainer(env, identifier, \"/path/to/compose\") with an absolute path to the binary.","Fix PATH in CI/IDE run configurations so the test JVM inherits the directory containing docker-compose."],"exampleFix":"// before: fails when only the v2 plugin exists\nnew DockerComposeContainer(new File(\"docker-compose.yml\"));\n\n// after: point at an existing compose binary/plugin shim\nnew DockerComposeContainer(new File(\"docker-compose.yml\"))\n    .withLocalCompose(true); // after installing docker-compose on PATH","handlingStrategy":"validation","validationCode":"// Run before starting DockerComposeContainer\nProcess p = new ProcessBuilder(\"docker-compose\", \"--version\").redirectErrorStream(true);\ntry {\n    if (p.start().waitFor() != 0) throw new IllegalStateException(\"docker-compose not usable on PATH\");\n} catch (java.io.IOException e) {\n    throw new IllegalStateException(\"docker-compose not found on PATH\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    composeContainer.start();\n} catch (ContainerLaunchException e) {\n    if (e.getMessage().contains(\"not found\")) {\n        throw new IllegalStateException(\"Install docker-compose and add it to PATH\", e);\n    }\n    throw e;\n}","preventionTips":["Install docker-compose in CI images and dev setup docs.","Check `which docker-compose` in CI pre-flight steps.","Ensure IDE/Gradle run configurations inherit the shell PATH.","If using Compose v2, create a docker-compose shim or upgrade the library."],"tags":["docker","docker-compose","path","missing-binary"],"backgroundTag":"command-not-found","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"}