quarkusio/quarkus · error · RuntimeException

Could not find builder image '${effectiveBuilderImage}' loca

Error message

Could not find builder image '${effectiveBuilderImage}' locally and 'quarkus.native.builder-image.pull' is set to 'never'.

What it means

When building a native image inside a container, Quarkus first checks whether the configured builder image (e.g. quay.io/quarkus/quarkus-mandrel-builder-image) exists locally. If the check shows the image is missing and quarkus.native.builder-image.pull=never, setup() aborts because it is forbidden from pulling and cannot continue without the image.

Source

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

            // will appear to block and no output will be shown
            String effectiveBuilderImage = nativeConfig.builderImage().getEffectiveImage();
            var builderImagePull = nativeConfig.builderImage().pull();
            if (builderImagePull != NativeConfig.ImagePullStrategy.ALWAYS) {
                log.infof("Checking status of builder image '%s'", effectiveBuilderImage);
                try {
                    var holder = new Object() {
                        int exitCode;
                    };
                    ProcessBuilder.newBuilder(containerRuntime.getExecutableName())
                            .arguments("image", "inspect", "-f", "{{ .Id }}", effectiveBuilderImage)
                            .exitCodeChecker(ec -> {
                                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);

View on GitHub (pinned to e1c734241f)

Solutions

1. Pull the builder image manually: docker pull <effectiveBuilderImage> (or podman pull)
2. Change quarkus.native.builder-image.pull to 'missing' (default) or 'always' so Quarkus may fetch the image
3. Correct the builder-image name/tag if it was misspelled
4. Verify the image exists in the container runtime Quarkus uses (docker vs podman) with docker image ls

Example fix

// before (application.properties)
quarkus.native.builder-image.pull=never
// after
quarkus.native.builder-image.pull=missing
// or pre-pull: docker pull quay.io/quarkus/quarkus-mandrel-builder-image:jdk-21

String img = "quay.io/quarkus/quarkus-mandrel-builder-image:jdk-21";
Process p = new ProcessBuilder("docker", "image", "inspect", img).redirectErrorStream(true).start();
if (p.waitFor() != 0) { /* pull it or change builder-image.pull */ }

try {
    buildNative();
} catch (RuntimeException e) {
    if (e.getMessage().contains("builder-image.pull' is set to 'never'")) {
        // pull image then retry once
    }
}

When it happens

Trigger: quarkus.native.builder-image.pull is set to 'never' (or pull=missing default behavior hitting the NEVER branch after a local-check failure reported exit code != 0) and the docker/podman local store does not contain the builder image tag.

Common situations: Air-gapped/CI environments with pull disabled; a pinned builder-image tag (e.g. a specific Mandrel version) that was never pulled; typos in the image name/tag; using a container runtime (podman vs docker) different from the one where the image was previously pulled.

Related errors

• Failed to check status of builder image '${effectiveBuilderI
• The native binary produced by the build is not a Linux binar
• The 'buildx' properties are specific to 'executable-name=doc
• Unable to save enhanced Dockerfile contents to disk
• The native binary produced by the build is not a Linux binar

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