quarkusio/quarkus · error · IllegalStateException

Buildpack build failed

Error message

Buildpack build failed

What it means

After running the buildpack builder process, runBuildpackBuild checks the process exit code; a non-zero code means the buildpack build itself failed (builder errors, missing pack binary, bad builder image, failed push), so an IllegalStateException is thrown.

Source

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

                        dc.endDockerConfig();

                        //configure lifecycle override image if present
                        buildpackConfig.lifecycleImage()
                                .ifPresent(
                                        li -> b.editPlatformConfig().withLifecycleImage(new ImageReference(li))
                                                .endPlatformConfig());

                        //force platform level, if present.
                        buildpackConfig.platformLevel()
                                .ifPresent(
                                        pl -> b.editPlatformConfig().withPlatformLevel(pl).endPlatformConfig());

                    })
                    .build()
                    .getExitCode();

            if (exitCode != 0) {
                throw new IllegalStateException("Buildpack build failed");
            }

            log.info("Buildpack build complete");
        }

        //if we built with registry mode, the build happened directly to the remote registry, so there is no need to publish
        //otherwise, now process the local image & publish to registry.
        if (pushContainerImage && Boolean.TRUE.equals(buildpackConfig.useDaemon())) {
            log.info("Pushing image to registry");
            Stream.concat(Stream.of(containerImage.getImage()), containerImage.getAdditionalImageTags().stream()).forEach(i -> {

                HostAndSocketConfig hns = DockerClientUtils.probeContainerRuntime(
                        new HostAndSocketConfig(buildpackConfig.dockerHost().orElse(null),
                                buildpackConfig.dockerSocket().orElse(null)));
                DockerClient dockerClient = DockerClientUtils.getDockerClient(hns, authConfigs);

                ResultCallback.Adapter<PushResponseItem> callback = new ResultCallback.Adapter<>() {
                    @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Inspect the buildpack builder logs printed before the exception for the root cause
2. Verify the configured builder image is valid and reachable (quarkus.buildpack.builder-image)
3. Check registry authentication and network access for pulling/pushing images
4. Ensure the pack/buildpack tooling and disk resources are available

Example fix

// before
quarkus.buildpack.builder-image=my-private-builder:latest  # unreachable
// after
quarkus.buildpack.builder-image=pack.local/builder/base:latest
quarkus.buildpack.auth-config=...  # valid credentials

// pre-checks before buildpack build
assertToolAvailable("pack");
assertImageReachable(config.builderImage());
assertRegistryCredentials(config.registry());

try {
    imageBuild();
} catch (IllegalStateException e) {
    if (e.getMessage().equals("Buildpack build failed")) {
        // inspect buildpack logs; fix builder/registry config and retry
    } else { throw e; }
}

When it happens

Trigger: The buildpack CLI/builder exits non-zero: invalid builder image, network failure pulling run/build images, insufficient disk space, or an error in generated application artifacts.

Common situations: Wrong or unreachable builder image (offline/air-gapped CI); misconfigured registry credentials during push; builder image incompatible with the project.

Related errors

• The native binary produced by the build is not a Linux binar
• Buildpack build unable to determine project dir
• Buildpack build unable to verify project dir
• Could not find builder image '${effectiveBuilderImage}' loca
• Task: %s requires extensions: %s. To add the extensions to t

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