quarkusio/quarkus · critical · RuntimeException

Docker Compose not found. Is ${composeExecutable} on the PAT

Error message

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

What it means

ComposeRunner.run() first verifies the configured compose executable exists on the PATH via CommandLine.executableExists(). If not found it throws RuntimeException("Docker Compose not found. Is <composeExecutable> on the PATH?"), aborting the DevServices startup that depends on compose.

Source

Thrown at extensions/devservices/deployment/src/main/java/io/quarkus/devservices/deployment/compose/ComposeRunner.java:85

    }

    /**
     * Set the profiles to use when running the command.
     *
     * @param profiles the profiles
     * @return this
     */
    public ComposeRunner withProfiles(List<String> profiles) {
        this.profiles = Collections.unmodifiableList(profiles);
        return this;
    }

    /**
     * Run the compose command.
     */
    public void run() {
        if (!CommandLine.executableExists(composeExecutable)) {
            throw new RuntimeException("Docker Compose not found. Is " + composeExecutable + " on the PATH?");
        }

        if (composeFiles.isEmpty()) {
            LOG.info("No compose files specified");
            return;
        }

        LOG.infov("Compose is running command: {0} {1}", composeExecutable, cmd);

        final File pwd = composeFiles.get(0).getAbsoluteFile().getParentFile().getAbsoluteFile();

        ProcessBuilder.newBuilder(composeExecutable)
                .directory(pwd.toPath())
                .arguments(cmd.split("\\s+"))
                .modifyEnvironment(env -> {
                    env.putAll(additionalEnvVars);

                    env.put(PROJECT_NAME_ENV, identifier);

View on GitHub (pinned to e1c734241f)

Solutions

1. Install Docker Compose (plugin: docker-compose-plugin / 'docker compose' subcommand, or standalone docker-compose) and ensure it is on PATH
2. Verify with 'docker compose version' (or 'docker-compose version') in the same shell/environment running Quarkus
3. If using a custom executable, set the composeExecutable configuration to an absolute path or install the named binary
4. Use Podman Compose alternatives that expose a docker-compatible compose command and point composeExecutable at it
5. Set quarkus.devservices.enabled=false only if you supply your own infrastructure instead

Example fix

# before
quarkus.devservices.compose.executable=compose  # binary not installed
# after (after installing docker compose plugin)
quarkus.devservices.compose.executable=docker  # resolved via 'docker compose'
# or simply ensure 'docker compose version' works before starting the app

// preflight before starting the app
for (String exe : List.of("docker", "docker")) {
    if (new ProcessBuilder(exe, "compose", "version").start().waitFor() != 0)
        throw new IllegalStateException("Docker Compose plugin required");
}

static boolean composeAvailable(String executable) {
    return CommandLine.executableExists(executable);
}

try {
    app.start();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Docker Compose not found")) {
        installComposeOrDisableDevServices();
    } else throw e;
}

When it happens

Trigger: Starting an application whose DevServices uses Docker Compose when neither 'docker compose' nor 'docker-compose' is installed; or when composeExecutable is set to a custom binary name/path that is not resolvable.

Common situations: Fresh machines or CI containers with Docker Compose plugin missing; minimal Docker installs (only daemon, no compose plugin); custom composeExecutable like 'podman-compose' not installed or not on PATH in the build environment.

Related errors

• Services have not been started yet
• Services named ${servicesToWaitFor} do not exist, but wait c
• Unsupported port format: ${port}
• Unable to find command: %s in $PATH: %s
• Cannot create a RunningDevServicesDatasource before the H2 d

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/13a7e36db83a0ede. Report an issue: GitHub.