quarkusio/quarkus · error · RuntimeException

Unable to build container image. Please check your %s instal

Error message

Unable to build container image. Please check your %s installation.

What it means

Before building a JVM-mode container image, the Docker (or Podman) processor checks whether a container runtime binary is available on the machine. If the runtime check build item reports no available runtime, the build fails with this RuntimeException naming the processor implementation (e.g. docker or podman).

Source

Thrown at extensions/container-image/container-image-docker-common/deployment/src/main/java/io/quarkus/container/image/docker/common/deployment/CommonProcessor.java:73

    protected void buildFromJar(C config,
            ContainerRuntimeStatusBuildItem containerRuntimeStatusBuildItem,
            ContainerImageConfig containerImageConfig,
            OutputTargetBuildItem out,
            ContainerImageInfoBuildItem containerImageInfo,
            Optional<ContainerImageBuildRequestBuildItem> buildRequest,
            Optional<ContainerImagePushRequestBuildItem> pushRequest,
            BuildProducer<ArtifactResultBuildItem> artifactResultProducer,
            BuildProducer<ContainerImageBuilderBuildItem> containerImageBuilder,
            PackageConfig packageConfig,
            ContainerRuntime... containerRuntimes) {

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

        if (buildContainerImage || pushContainerImage) {
            if (!containerRuntimeStatusBuildItem.isContainerRuntimeAvailable()) {
                throw new RuntimeException(
                        "Unable to build container image. Please check your %s installation."
                                .formatted(getProcessorImplementation()));
            }

            var dockerfilePaths = getDockerfilePaths(config, false, packageConfig, out);
            var dockerfileBaseInformation = DockerFileBaseInformationProvider.impl()
                    .determine(dockerfilePaths.dockerfilePath());

            if (dockerfileBaseInformation.isPresent() && (dockerfileBaseInformation.get().javaVersion() < 17)) {
                throw new IllegalStateException(
                        "The project is built with Java 17 or higher, but the selected Dockerfile (%s) is using a lower Java version in the base image (%s). Please ensure you are using the proper base image in the Dockerfile."
                                .formatted(
                                        dockerfilePaths.dockerfilePath().toAbsolutePath(),
                                        dockerfileBaseInformation.get().baseImage()));
            }

            if (buildContainerImage) {
                LOGGER.infof("Starting (local) container image build for jar using %s", getProcessorImplementation());

View on GitHub (pinned to e1c734241f)

Solutions

1. Install/start Docker (or Podman) and ensure the CLI is on PATH
2. Start the Docker daemon / Docker Desktop before building
3. In CI, add a docker-in-docker service or install podman in the job image
4. Verify with 'docker info' (or 'podman info') that the runtime responds
5. Use a remote/alternate runtime via quarkus.container-image.* configuration if local docker is impossible

Example fix

// before (CI job without docker)
./mvnw package -Dquarkus.container-image.build=true
// after (GitLab CI with dind service)
services: ['docker:dind']
variables:
  DOCKER_HOST: tcp://docker:2376

boolean runtimeAvailable(String... cmds) {
    for (String cmd : cmds) {
        try {
            Process p = new ProcessBuilder(cmd, "info").redirectErrorStream(true).start();
            if (p.waitFor(30, java.util.concurrent.TimeUnit.SECONDS) && p.exitValue() == 0) return true;
        } catch (Exception ignored) { }
    }
    return false;
}
// call: runtimeAvailable("docker", "podman")

boolean isDockerUsable() throws IOException, InterruptedException {
    Process p = new ProcessBuilder("docker", "info").start();
    return p.waitFor() == 0;
}

try {
    buildContainerImage();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("check your")) {
        throw new IllegalStateException("Install/start Docker or Podman before building images", e);
    }
    throw e;
}

When it happens

Trigger: Running quarkus.container-image.build=true (or -Dquarkus.container-image.build) for a JVM package while neither docker nor podman is installed, not on PATH, or the daemon is unreachable so the runtime probe fails.

Common situations: Docker Desktop not started, CI runner without Docker daemon (no docker:dind service), podman not installed in the build container, docker binary exists but 'docker info' fails due to permissions (user not in docker group).

Related errors

• No container CLI was found. Make sure you have either Docker
• Unable to find command: %s in $PATH: %s
• Failed to check status of builder image '${effectiveBuilderI
• Cannot get an executable name when no container runtime is a
• No system java compiler provided

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