quarkusio/quarkus · error · IllegalStateException

Cannot get an executable name when no container runtime is a

Error message

Cannot get an executable name when no container runtime is available

What it means

ContainerRuntime.ContainerRuntime.getExecutableName() returns the CLI executable name for a detected runtime. Calling it on the sentinel UNAVAILABLE enum value throws IllegalStateException("Cannot get an executable name when no container runtime is available") — the sentinel has no associated executable.

Source

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

        DOCKER_ROOTLESS("docker", true),
        WSL("docker", false),
        WSL_ROOTLESS("docker", false),
        PODMAN("podman", false),
        PODMAN_ROOTLESS("podman", true),
        UNAVAILABLE(null, false);

        private final String executableName;

        private final boolean rootless;

        ContainerRuntime(String executableName, boolean rootless) {
            this.executableName = executableName;
            this.rootless = rootless;
        }

        public String getExecutableName() {
            if (this == UNAVAILABLE) {
                throw new IllegalStateException("Cannot get an executable name when no container runtime is available");
            }

            return executableName;
        }

        public boolean isDocker() {
            return this == DOCKER || this == DOCKER_ROOTLESS || this == WSL || this == WSL_ROOTLESS;
        }

        public boolean isPodman() {
            return this == PODMAN || this == PODMAN_ROOTLESS;
        }

        public boolean isInWindowsWSL() {
            return this == WSL || this == WSL_ROOTLESS;
        }

        public boolean isRootless() {

View on GitHub (pinned to e1c734241f)

Solutions

Check runtime != ContainerRuntime.UNAVAILABLE before calling getExecutableName()
When detection is optional, branch on UNAVAILABLE and skip container operations
If detection should always succeed, call detectContainerRuntime() (required=true) so it fails fast with the clearer install-Docker/Podman message

Example fix

// before
String exe = ContainerRuntimeUtil.detectContainerRuntime(false).getExecutableName();
// after
ContainerRuntime rt = ContainerRuntimeUtil.detectContainerRuntime(false);
String exe = rt == ContainerRuntime.UNAVAILABLE ? null : rt.getExecutableName();

Defensive patterns

Strategy: type-guard

Validate before calling

static boolean hasRuntime(ContainerRuntime rt) {
    return rt != ContainerRuntime.UNAVAILABLE;
}

Type guard

if (rt != ContainerRuntime.UNAVAILABLE) {
    String exe = rt.getExecutableName();
}

Try / catch

try {
    String exe = rt.getExecutableName();
} catch (IllegalStateException e) {
    // rt was UNAVAILABLE — handle the no-container case
    return null;
}

Prevention

Always compare against ContainerRuntime.UNAVAILABLE after detectContainerRuntime(required=false)
Use detectContainerRuntime() (required=true) when the executable name is definitely needed, to fail with the clearer message
Never cache ContainerRuntime values across environments without re-checking UNAVAILABLE

When it happens

Trigger: Code obtains a ContainerRuntime via detectContainerRuntime(false) (which may return UNAVAILABLE), or from a system property storing UNAVAILABLE, and then calls getExecutableName() on it without checking.

Common situations: Extension code or user code doing optional detection then unconditionally reading the executable name; caching a ContainerRuntime from an environment where no CLI was installed and reusing it later.

Related errors

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