{"record":{"id":"db49822c0564d6fe","repo":"quarkusio/quarkus","slug":"could-not-find-builder-image-effectivebuilderim","errorCode":null,"errorMessage":"Could not find builder image '${effectiveBuilderImage}' locally and 'quarkus.native.builder-image.pull' is set to 'never'.","messagePattern":"Could not find builder image '(.+?)' locally and 'quarkus\\.native\\.builder-image\\.pull' is set to 'never'\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"core/deployment/src/main/java/io/quarkus/deployment/pkg/steps/NativeImageBuildContainerRunner.java","lineNumber":69,"sourceCode":"            // will appear to block and no output will be shown\n            String effectiveBuilderImage = nativeConfig.builderImage().getEffectiveImage();\n            var builderImagePull = nativeConfig.builderImage().pull();\n            if (builderImagePull != NativeConfig.ImagePullStrategy.ALWAYS) {\n                log.infof(\"Checking status of builder image '%s'\", effectiveBuilderImage);\n                try {\n                    var holder = new Object() {\n                        int exitCode;\n                    };\n                    ProcessBuilder.newBuilder(containerRuntime.getExecutableName())\n                            .arguments(\"image\", \"inspect\", \"-f\", \"{{ .Id }}\", effectiveBuilderImage)\n                            .exitCodeChecker(ec -> {\n                                holder.exitCode = ec;\n                                return true;\n                            })\n                            .run();\n                    if (holder.exitCode != 0) {\n                        if (builderImagePull == NativeConfig.ImagePullStrategy.NEVER) {\n                            throw new RuntimeException(\n                                    \"Could not find builder image '\" + effectiveBuilderImage\n                                            + \"' locally and 'quarkus.native.builder-image.pull' is set to 'never'.\");\n                        } else {\n                            log.infof(\"Could not find builder image '%s' locally, pulling the builder image\",\n                                    effectiveBuilderImage);\n                        }\n                    } else {\n                        log.infof(\"Found builder image '%s' locally, skipping image pulling\", effectiveBuilderImage);\n                        return;\n                    }\n                } catch (Exception e) {\n                    throw new RuntimeException(\"Failed to check status of builder image '\" + effectiveBuilderImage + \"'\", e);\n                }\n            }\n\n            try {\n                log.infof(\"Pulling builder image '%s'\", effectiveBuilderImage);\n                pull(effectiveBuilderImage, processInheritIODisabled);","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/deployment/src/main/java/io/quarkus/deployment/pkg/steps/NativeImageBuildContainerRunner.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pull the builder image manually: docker pull <effectiveBuilderImage> (or podman pull)","Change quarkus.native.builder-image.pull to 'missing' (default) or 'always' so Quarkus may fetch the image","Correct the builder-image name/tag if it was misspelled","Verify the image exists in the container runtime Quarkus uses (docker vs podman) with docker image ls"],"exampleFix":"// before (application.properties)\nquarkus.native.builder-image.pull=never\n// after\nquarkus.native.builder-image.pull=missing\n// or pre-pull: docker pull quay.io/quarkus/quarkus-mandrel-builder-image:jdk-21","handlingStrategy":"fallback","validationCode":"String img = \"quay.io/quarkus/quarkus-mandrel-builder-image:jdk-21\";\nProcess p = new ProcessBuilder(\"docker\", \"image\", \"inspect\", img).redirectErrorStream(true).start();\nif (p.waitFor() != 0) { /* pull it or change builder-image.pull */ }","typeGuard":null,"tryCatchPattern":"try {\n    buildNative();\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"builder-image.pull' is set to 'never'\")) {\n        // pull image then retry once\n    }\n}","preventionTips":["Keep the default pull strategy (missing) unless air-gapped","Pre-pull pinned builder images in CI setup steps","Verify image tags exist before pinning versions"],"tags":["docker","container-image","native-image","configuration"],"backgroundTag":"container-image-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}