quarkusio/quarkus · error · RuntimeException

Unable to find ${name} command

Error message

Unable to find ${name} command

What it means

Executable.findExecutable locates a named command-line tool (via findExecutableFile, searching PATH). If it cannot find the executable it logs the supplied errorMessage and throws a plain RuntimeException 'Unable to find <name> command'. Used e.g. for docker, podman or other tooling required by devtools workflows.

Source

Thrown at independent-projects/tools/devtools-common/src/main/java/io/quarkus/devtools/exec/Executable.java:40

            }
        } else {
            executable = base;
            path = findExecutable(executable);
        }
        if (path == null)
            return null;
        return new File(path);
    }

    public static String findExecutable(String exec) {
        return ProcessUtil.pathOfCommand(Path.of(exec)).map(Object::toString).orElse(null);
    }

    public static File findExecutable(String name, String errorMessage, MessageWriter output) {
        File command = findExecutableFile(name);
        if (command == null) {
            output.error(errorMessage);
            throw new RuntimeException("Unable to find " + name + " command");
        }
        return command;
    }

    public static File findWrapper(Path projectRoot, String[] windows, String other) {
        if (projectRoot == null) {
            return null;
        }
        if (OS.current() == OS.WINDOWS) {
            for (String name : windows) {
                File wrapper = new File(projectRoot + File.separator + name);
                if (wrapper.isFile())
                    return wrapper;
            }
        } else {
            File wrapper = new File(projectRoot + File.separator + other);
            if (wrapper.isFile())
                return wrapper;

View on GitHub (pinned to e1c734241f)

Solutions

1. Install the required tool or add its directory to PATH (verify with `which <name>`).
2. In CI, use an image that includes the tool (e.g. docker:cli) or install it in a setup step.
3. If the tool is a wrapper (mvnw/gradlew), ensure project root is correct so findWrapper can locate it.
4. Check PATH inside containers/systemd contexts where it differs from your shell.

Example fix

// before (shell)
quarkus dev // fails: Unable to find docker command
// after
export PATH=/usr/local/bin:$PATH  # or: apt-get install -y docker-cli

// Check the tool is on PATH before invoking devtools workflows
static boolean commandOnPath(String name) {
    return java.util.Arrays.stream(System.getenv("PATH").split(java.io.File.pathSeparator))
        .anyMatch(dir -> new File(dir, name).canExecute());
}
if (!commandOnPath("docker")) throw new IllegalStateException("docker not found on PATH");

try {
    File docker = Executable.findExecutable("docker", "Docker is required", writer);
} catch (RuntimeException e) {
    if (e.getMessage().equals("Unable to find docker command")) {
        // install the tool or fix PATH, then retry
    } else throw e;
}

When it happens

Trigger: findExecutable("docker"|other tool, ...) when the binary is not on PATH — findExecutableFile returns null and the RuntimeException is thrown at Executable.java:40.

Common situations: Docker/Podman not installed or not on PATH; running in a slim CI image without the tool; container-in-container environments; misspelled executable name; tool installed only for another user.

Related errors

• Unable to find command: %s in $PATH: %s
• Cannot locate mvnw or mvn. Make sure mvnw is in the project
• Cannot gradlew mvnw or gradle. Make sure gradlew is in the c
• No system java compiler provided
• No container CLI was found. Make sure you have either Docker

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