quarkusio/quarkus · critical · IllegalStateException

No container CLI was found. Make sure you have either Docker

Error message

No container CLI was found. Make sure you have either Docker or Podman CLI installed in your environment.

What it means

ContainerRuntimeUtil.detectContainerRuntime(required=true) probes for a Docker or Podman CLI in $PATH (honoring the quarkus.native.container-runtime system property / detection order). If neither executable is found and a container runtime is required, it throws IllegalStateException telling the user to install Docker or Podman. Used by container-based builds (e.g. native image builds in container, Dev Services image operations).

Source

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

    }

    public static ContainerRuntime detectContainerRuntime(boolean required, List<ContainerRuntime> orderToCheckRuntimes) {
        return detectContainerRuntime(required, false, orderToCheckRuntimes);
    }

    public static ContainerRuntime detectContainerRuntime(boolean required, boolean silent,
            List<ContainerRuntime> orderToCheckRuntimes) {
        ContainerRuntime containerRuntime = loadContainerRuntimeFromSystemProperty();
        if ((containerRuntime != null) && orderToCheckRuntimes.contains(containerRuntime)) {
            return containerRuntime;
        }

        final ContainerRuntime containerRuntimeEnvironment = getContainerRuntimeEnvironment(orderToCheckRuntimes);
        if (containerRuntimeEnvironment == ContainerRuntime.UNAVAILABLE) {
            storeContainerRuntimeInSystemProperty(ContainerRuntime.UNAVAILABLE);

            if (required) {
                throw new IllegalStateException("No container CLI was found. "
                        + "Make sure you have either Docker or Podman CLI installed in your environment.");
            }

            return ContainerRuntime.UNAVAILABLE;
        }

        // we have a working container environment, let's resolve it fully
        containerRuntime = fullyResolveContainerRuntime(containerRuntimeEnvironment, silent);

        storeContainerRuntimeInSystemProperty(containerRuntime);

        return containerRuntime;
    }

    private static ContainerRuntime getContainerRuntimeEnvironment(List<ContainerRuntime> orderToCheckRuntimes) {
        // Docker version 19.03.14, build 5eb3275d40

        // Check if Podman is installed

View on GitHub (pinned to e1c734241f)

Solutions

Install Docker Desktop/Engine or Podman and ensure the CLI is on $PATH (docker version / podman version must work)
If the runtime is installed but not detected, set -Dquarkus.native.container-runtime=podman (or docker) explicitly
If you don't need container-based builds, drop -Dquarkus.native.container-build=true and use a local GraalVM instead
For container-image builds, check the daemon is running; if you only need detection to be optional use detectContainerRuntime(false)

Example fix

// before (CI without docker)
mvn package -Dnative -Dquarkus.native.container-build=true
// after (option A: install docker CLI+daemon, or option B: local GraalVM)
mvn package -Dnative -Dquarkus.graalvm.home=/path/to/graalvm

Defensive patterns

Strategy: fallback

Validate before calling

static void requireContainerCli() {
    try {
        new ProcessBuilder("docker", "version").start();
    } catch (Exception e1) {
        try {
            new ProcessBuilder("podman", "version").start();
        } catch (Exception e2) {
            throw new IllegalStateException("Neither docker nor podman CLI found on PATH");
        }
    }
}

Try / catch

try {
    ContainerRuntimeUtil.detectContainerRuntime();
} catch (IllegalStateException e) {
    throw new IllegalStateException("Install Docker/Podman or disable container builds (-Dquarkus.native.container-build=false)", e);
}

Prevention

Verify `docker version` or `podman version` works in the same environment/user that runs the build
In CI images, install docker-cli (or podman) as part of the image
Set -Dquarkus.native.container-runtime=docker|podman when both may be present
Use local GraalVM builds to avoid needing a container CLI at all

When it happens

Trigger: Running a Quarkus build step that requires a container (e.g. mvn package -Dnative -Dquarkus.native.container-build=true) on a machine with no docker or podman executable on $PATH; or detection is restricted via detectContainerRuntime(required, orderToCheckRuntimes) to runtimes that are absent.

Common situations: CI containers without Docker socket/CLI; Docker Desktop not installed; running inside an already-containerized build where nested Docker is unavailable; typo in quarkus.native.container-runtime so it is ignored.

Related errors

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