quarkusio/quarkus · error · RuntimeException

Failed to check status of builder image '${effectiveBuilderI

Error message

Failed to check status of builder image '${effectiveBuilderImage}'

What it means

Before pulling the native builder image, Quarkus runs a command (e.g. 'docker inspect'/'podman image exists') to determine if the image is available locally. If that inspection command itself fails with an exception, setup() wraps it in this RuntimeException so the underlying cause (daemon not running, runtime not installed, permissions) is preserved.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/pkg/steps/NativeImageBuildContainerRunner.java:81

                                holder.exitCode = ec;
                                return true;
                            })
                            .run();
                    if (holder.exitCode != 0) {
                        if (builderImagePull == NativeConfig.ImagePullStrategy.NEVER) {
                            throw new RuntimeException(
                                    "Could not find builder image '" + effectiveBuilderImage
                                            + "' locally and 'quarkus.native.builder-image.pull' is set to 'never'.");
                        } else {
                            log.infof("Could not find builder image '%s' locally, pulling the builder image",
                                    effectiveBuilderImage);
                        }
                    } else {
                        log.infof("Found builder image '%s' locally, skipping image pulling", effectiveBuilderImage);
                        return;
                    }
                } catch (Exception e) {
                    throw new RuntimeException("Failed to check status of builder image '" + effectiveBuilderImage + "'", e);
                }
            }

            try {
                log.infof("Pulling builder image '%s'", effectiveBuilderImage);
                pull(effectiveBuilderImage, processInheritIODisabled);
            } catch (Exception e) {
                log.infof("Retrying in 5 seconds");
                try {
                    Thread.sleep(5_000L);
                } catch (InterruptedException e1) {
                    throw new RuntimeException(e1);
                }
                log.infof("Pulling builder image '%s' (take 2)", effectiveBuilderImage);
                pull(effectiveBuilderImage, processInheritIODisabled);
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

Read the 'Caused by' of this exception to identify the underlying container-runtime failure
Start the Docker/Podman daemon (systemctl start docker / podman system service, or launch Docker Desktop)
Ensure the container runtime binary is on PATH and Quarkus points at the right one (quarkus.native.container-runtime=docker|podman)
As a workaround, pull the builder image manually so the status check is skipped

Example fix

// before: daemon stopped -> inspection throws
sudo systemctl start docker
// or pin the runtime you actually have
quarkus.native.container-runtime=podman

Defensive patterns

Strategy: retry

Validate before calling

try {
    new ProcessBuilder("docker", "info").start().waitFor();
} catch (Exception e) {
    throw new IllegalStateException("Container runtime unavailable before native build", e);
}

Try / catch

try {
    buildNative();
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to check status of builder image")) {
        // inspect e.getCause(); ensure daemon is running, then retry
    }
}

Prevention

Ensure Docker/Podman daemon is healthy before builds
Set quarkus.native.container-runtime explicitly to the installed runtime
Pre-pull the builder image so the status-check path is skipped

When it happens

Trigger: The local image-inspection command throws when executed — e.g. Docker/Podman daemon not running, container runtime binary missing from PATH, or the status-check subprocess fails unexpectedly while quarkus.native.builder-image.pull=missing and the image has not been pulled.

Common situations: CI runners where the Docker daemon isn't started; podman-in-podman setups; Docker Desktop not running locally; insufficient permissions to talk to the container runtime socket.

Related errors

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