quarkusio/quarkus · error · IllegalStateException

Unable to find command: %s in $PATH: %s

Error message

Unable to find command: %s in $PATH: %s

What it means

After a container runtime CLI is detected, ContainerRuntimeUtil.fullyResolveContainerRuntime resolves its full identity (rootless/WSL variants) by locating the executable with ProcessUtil.pathOfCommand. If the executable name exists during version probing but cannot be resolved to a Path, it throws IllegalStateException("Unable to find command: %s in $PATH: %s"). The code comments this 'should never happen', so it usually indicates PATH changed mid-build or detection ran with a non-PATH-resolvable executable.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/util/ContainerRuntimeUtil.java:156

                case PODMAN_ROOTLESS:
                    if (PODMAN_PATTERN.matcher(versionOutput).matches()) {
                        return ContainerRuntime.PODMAN;
                    }
                    break;
            }
        }

        return ContainerRuntime.UNAVAILABLE;
    }

    private static ContainerRuntime fullyResolveContainerRuntime(ContainerRuntime containerRuntimeEnvironment,
            boolean silent) {
        String execName = containerRuntimeEnvironment.getExecutableName();
        try {
            Optional<Path> execPath = ProcessUtil.pathOfCommand(Path.of(execName));
            if (execPath.isEmpty()) {
                // this should never happen as we have detected the presence of the Docker/Podman CLI before
                throw new IllegalStateException(
                        String.format("Unable to find command: %s in $PATH: %s", execName, ProcessUtil.searchPath()));
            }

            return ProcessBuilder.newBuilder(execPath.get())
                    .arguments("info")
                    .output().gatherOnFail(true).processWith(br -> {
                        boolean rootless = false;
                        boolean isInWindowsWSL = false;
                        boolean isDocker = containerRuntimeEnvironment.isDocker();
                        String line;
                        while ((line = br.readLine()) != null) {
                            if (isDocker) {
                                if (line.trim().equals("rootless") || line.contains("Docker Desktop")
                                        || line.contains("desktop-linux")) {
                                    rootless = true;
                                }
                            } else {
                                if (line.trim().equals("rootless: true")) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the $PATH printed in the message and ensure the docker/podman binary's directory is in it for the process running the build
2. Verify the executable is a real on-disk binary, not a shell alias/function: which docker / command -v docker
3. Align PATH between your IDE/CI launcher and shell (launch Maven from a login shell or set PATH in CI config)
4. Set -Dquarkus.native.container-runtime=docker|podman to force a known-good runtime name

Example fix

// before: alias set in ~/.bashrc, not visible to Maven
alias docker=podman
// after: ensure a real binary on PATH (e.g. symlink)
sudo ln -s $(command -v podman) /usr/local/bin/docker

static boolean resolvableOnPath(String exec) {
    return ProcessUtil.pathOfCommand(java.nio.file.Path.of(exec)).isPresent();
}
// call before build: require resolvableOnPath("docker") || resolvableOnPath("podman")

try {
    ContainerRuntime rt = ContainerRuntimeUtil.detectContainerRuntime();
} catch (IllegalStateException e) {
    // message contains the $PATH actually used — fix PATH for this process and retry
}

When it happens

Trigger: docker/podman passed detection (version probe succeeded) but ProcessUtil.pathOfCommand(Path.of("docker")) returns empty — e.g. the 'executable' matched via CONTAINER_EXECUTABLE config is an alias/function not a real file, PATH was mutated between checks, or a wrapper script named differently is resolved inconsistently.

Common situations: quarkus.native.container-runtime set to a custom wrapper name; PATH differs between the Maven process and shell (IDE-launched builds); Docker Desktop's docker CLI installed in a user-specific path not in the Maven process's PATH.

Related errors

• No container CLI was found. Make sure you have either Docker
• Unable to build container image. Please check your %s instal
• Cannot get an executable name when no container runtime is a
• Unable to find ${name} command
• Cannot locate mvnw or mvn. Make sure mvnw is in the project

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