{"record":{"id":"cc22a15c5796eed8","repo":"testcontainers/testcontainers-java","slug":"local-docker-compose-exited-abnormally-with-code-exitvalue","errorCode":null,"errorMessage":"Local Docker Compose exited abnormally with code ${exitValue} whilst running command: ${cmd}","messagePattern":"Local Docker Compose exited abnormally with code (.+?) whilst running command: (.+?)","errorType":"exception","errorClass":"ContainerLaunchException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/LocalDockerCompose.java","lineNumber":117,"sourceCode":"\n        final List<String> command = Splitter\n            .onPattern(\" \")\n            .omitEmptyStrings()\n            .splitToList(this.composeExecutable + \" \" + cmd);\n\n        try {\n            new ProcessExecutor()\n                .command(command)\n                .redirectOutput(Slf4jStream.of(logger()).asInfo())\n                .redirectError(Slf4jStream.of(logger()).asInfo()) // docker-compose will log pull information to stderr\n                .environment(environment)\n                .directory(pwd)\n                .exitValueNormal()\n                .executeNoTimeout();\n\n            logger().info(\"Docker Compose has finished running\");\n        } catch (InvalidExitValueException e) {\n            throw new ContainerLaunchException(\n                \"Local Docker Compose exited abnormally with code \" +\n                e.getExitValue() +\n                \" whilst running command: \" +\n                cmd\n            );\n        } catch (Exception e) {\n            throw new ContainerLaunchException(\"Error running local Docker Compose command: \" + cmd, e);\n        }\n    }\n\n    /**\n     * @return a logger\n     */\n    private Logger logger() {\n        return DockerLoggerFactory.getLogger(this.composeExecutable);\n    }\n}\n","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/LocalDockerCompose.java#L99-L135","documentation":"Thrown by LocalDockerCompose.invoke() as a ContainerLaunchException when the docker-compose process runs but exits with a non-zero status (InvalidExitValueException from the executeNoTimeout() call). The message includes the abnormal exit code and the full compose command, meaning the compose invocation itself failed (bad compose file, pull failure, build error, etc.).","triggerScenarios":"DockerComposeContainer.start() driving LocalDockerCompose where `docker-compose up ...` executed in pwd returns a non-zero exitValue — e.g. invalid YAML, missing image, port conflicts, or build failures; caught from org.zeroturnaround.exec's InvalidExitValueException.","commonSituations":"Compose files referencing images that cannot be pulled (network/registry auth issues); services failing healthchecks so compose exits non-zero; compose file version incompatibilities between the installed binary and the file; Docker daemon not running at all (exit code 1).","solutions":["Read the compose output in the test logs immediately above the exception — it contains the actual docker-compose error; fix that root cause.","Run the same command locally (it is included in the message) in the working directory to reproduce and debug the failure.","Verify the Docker daemon is running and the compose file is valid: `docker info` and `docker-compose -f <file> config`.","Check image names/tags, registry credentials, and port bindings referenced by the compose file in the CI environment."],"exampleFix":"// before: compose file references an image unavailable in CI\nservices:\n  db:\n    image: internal-registry/db:latest\n\n// after: pin a pullable tag / add auth\nservices:\n  db:\n    image: internal-registry/db:1.4.2","handlingStrategy":"try-catch","validationCode":"// Validate the compose file before running the container\nnew ProcessBuilder(\"docker-compose\", \"-f\", \"docker-compose.yml\", \"config\")\n    .inheritIO().start().waitFor(); // non-zero => invalid compose file","typeGuard":null,"tryCatchPattern":"try {\n    composeContainer.start();\n} catch (ContainerLaunchException e) {\n    if (e.getMessage().contains(\"exited abnormally\")) {\n        // message contains the compose command; rerun it for full diagnostics\n        throw new IllegalStateException(\"docker-compose failed: \" + e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Lint the compose file (`docker-compose config`) in CI before tests.","Pin image tags and pre-pull them in CI to avoid registry flakiness.","Ensure the Docker daemon is healthy before the test phase.","Keep compose file version compatible with the installed binary."],"tags":["docker","docker-compose","process-exit","launch-failure"],"backgroundTag":"http-request-failed","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"}