quarkusio/quarkus · error · RuntimeException

The native binary produced by the build is not a Linux binar

Error message

The native binary produced by the build is not a Linux binary and therefore cannot be used in a Linux container image. Consider adding "quarkus.native.container-build=true" to your configuration

What it means

BuildpackProcessor.buildFromNative refuses to build a container image when the native binary produced by the Quarkus build is not a Linux binary, because it cannot be used in a Linux container image. This typically occurs when building a native executable for the local host OS (e.g. macOS/Windows) instead of a Linux target.

Source

Thrown at extensions/container-image/container-image-buildpack/deployment/src/main/java/io/quarkus/container/image/buildpack/deployment/BuildpackProcessor.java:129

            Optional<ContainerImageBuildRequestBuildItem> buildRequest,
            Optional<ContainerImagePushRequestBuildItem> pushRequest,
            List<ContainerImageLabelBuildItem> containerImageLabels,
            BuildProducer<ArtifactResultBuildItem> artifactResultProducer,
            BuildProducer<ContainerImageBuilderBuildItem> containerImageBuilder) {

        boolean buildContainerImage = buildContainerImageNeeded(containerImageConfig, buildRequest);
        boolean pushContainerImage = pushContainerImageNeeded(containerImageConfig, pushRequest);

        if (!buildContainerImage && !pushContainerImage) {
            return;
        }

        if (containerImageConfig.isBuildExplicitlyDisabled()) {
            return;
        }

        if (!NativeBinaryUtil.nativeIsLinuxBinary(nativeImage)) {
            throw new RuntimeException(
                    "The native binary produced by the build is not a Linux binary and therefore cannot be used in a Linux container image. Consider adding \"quarkus.native.container-build=true\" to your configuration");
        }

        log.info("Starting (local) container image build for native binary using buildpack.");
        String targetImageName = runBuildpackBuild(buildpackConfig, containerImage, containerImageConfig, buildContainerImage,
                pushContainerImage,
                outputTarget, true /* isNative */);

        artifactResultProducer.produce(new ArtifactResultBuildItem(null, "native-container",
                Collections.singletonMap("container-image", targetImageName)));
        containerImageBuilder.produce(new ContainerImageBuilderBuildItem(BUILDPACK));
    }

    private Map<ProjectDirs, Path> getPaths(OutputTargetBuildItem outputTarget) {

        Path targetDirectory = outputTarget.getOutputDirectory();

        Map.Entry<Path, Path> mainSourcesRoot = findMainSourcesRoot(targetDirectory);

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.native.container-build=true so the native image is built inside a Linux container
Or build with -Dquarkus.native.container-build=true on the command line
Or produce a Linux binary explicitly (e.g. target linux/musl) before the image build

Example fix

// before
./mvnw package -Pnative -Dquarkus.container-image.build=true
// after
./mvnw package -Pnative -Dquarkus.container-image.build=true -Dquarkus.native.container-build=true

Defensive patterns

Strategy: validation

Validate before calling

// build a Linux native binary before the container build
./mvnw package -Pnative -Dquarkus.native.container-build=true
// verify before image build:
if (!quarkus.native.containerBuild && !hostOsIsLinux()) {
    throw new IllegalStateException("enable quarkus.native.container-build=true");
}

Try / catch

try {
    quarkusBuild();
} catch (RuntimeException e) {
    if (e.getMessage().contains("not a Linux binary")) {
        // rerun with -Dquarkus.native.container-build=true
    } else { throw e; }
}

Prevention

Always pass -Dquarkus.native.container-build=true on non-Linux hosts when building native container images
Keep container-build flag in CI pipelines and Maven/Gradle profiles

When it happens

Trigger: Running a buildpack container-image build over a native binary built without quarkus.native.container-build=true (or without a Linux-musl target), so nativeImage targets the local OS.

Common situations: Developers on macOS/Windows building natively with a local GraalVM then attempting docker/buildpack image creation; CI without the container-build flag.

Related errors

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