quarkusio/quarkus · error · IllegalArgumentException

The 'buildx' properties are specific to 'executable-name=doc

Error message

The 'buildx' properties are specific to 'executable-name=docker' and can not be used with the '%s' executable name. Either remove the `buildx` properties or the `executable-name` property.

What it means

DockerProcessor.getDockerBuildArgs rejects the build when buildx options are enabled but the executable name is not 'docker', since buildx is a Docker CLI plugin and cannot work with podman or other executables. The error names the offending executable and the conflicting properties.

Source

Thrown at extensions/container-image/container-image-docker/deployment/src/main/java/io/quarkus/container/image/docker/deployment/DockerProcessor.java:189

        return executableName;
    }

    private String[] getDockerBuildArgs(String image,
            DockerfilePaths dockerfilePaths,
            ContainerImageConfig containerImageConfig,
            DockerConfig dockerConfig,
            boolean pushImages,
            String executableName,
            List<String> additionalImageTags) {

        var dockerBuildArgs = getContainerCommonBuildArgs(image, dockerfilePaths, containerImageConfig, dockerConfig, true);
        var buildx = dockerConfig.buildx();
        var useBuildx = buildx.useBuildx();

        if (useBuildx) {
            // Check the executable. If not 'docker', then fail the build
            if (!DOCKER.equals(executableName)) {
                throw new IllegalArgumentException(
                        "The 'buildx' properties are specific to 'executable-name=docker' and can not be used with the '%s' executable name. Either remove the `buildx` properties or the `executable-name` property."
                                .formatted(executableName));
            }

            dockerBuildArgs.add(0, "buildx");
        }

        buildx.platform()
                .filter(platform -> !platform.isEmpty())
                .ifPresent(platform -> {
                    dockerBuildArgs.addAll(List.of("--platform", String.join(",", platform)));

                    if (platform.size() == 1) {
                        // Buildx only supports loading the image to the docker system if there is only 1 image
                        dockerBuildArgs.add("--load");
                    }
                });

View on GitHub (pinned to e1c734241f)

Solutions

1. Remove the quarkus.docker.buildx.* properties when using a non-docker executable
2. Or set quarkus.docker.executable-name=docker (default) to keep buildx
3. Disable use-buildx explicitly: quarkus.docker.buildx.use-buildx=false

Example fix

// before (application.properties)
quarkus.docker.executable-name=podman
quarkus.docker.buildx.use-buildx=true
// after
quarkus.docker.executable-name=podman
# buildx properties removed

// fail fast when config conflicts
if (!"docker".equals(config.executableName()) && config.buildx().useBuildx()) {
    throw new IllegalArgumentException("buildx requires executable-name=docker");
}

try {
    imageBuild();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("'buildx' properties")) {
        // drop buildx.* properties or switch executable-name to docker
    } else { throw e; }
}

When it happens

Trigger: Configuring quarkus.docker.executable-name=podman (or similar) together with quarkus.docker.buildx.use-buildx=true (or any buildx.* option).

Common situations: Switching from docker to podman while leaving buildx settings enabled; copying config between projects with different container engines.

Related errors

• Could not find builder image '${effectiveBuilderImage}' loca
• Unable to determine project root
• Specified Dockerfile path %s does not exist
• Failed to load application configuration
• Failed to initialize application configuration

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