microsoft/aspire · error · DistributedApplicationException

Docker buildx is not available. Install the buildx plugin…

Error message

Docker buildx is not available. Install the buildx plugin and try again.

What it means

Docker image builds in Aspire rely on the 'docker buildx' plugin rather than the legacy builder. BuildImageAsync probes for buildx availability first (CheckDockerBuildxAsync) and throws DistributedApplicationException if it is missing, giving a clear install hint instead of an obscure 'docker build' failure.

Solutions

1. Install the buildx plugin: 'docker buildx install' via package (apt install docker-buildx-plugin) or download the plugin binary into the CLI plugins directory.
2. Upgrade Docker Desktop / Docker Engine to a recent version that ships buildx.
3. Verify with 'docker buildx version' before running the app host.
4. Use a runtime that does not require buildx if the build features are not needed.

Example fix

// before: docker.io installed on Ubuntu without buildx
sudo apt-get install -y docker.io
// after
sudo apt-get install -y docker.io docker-buildx-plugin
docker buildx version

var probe = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo("docker", "buildx version") { RedirectStandardOutput = true, RedirectStandardError = true });
probe?.WaitForExit(5000);
if (probe?.ExitCode != 0)
{
    throw new InvalidOperationException("docker buildx plugin is required for image builds.");
}

try
{
    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("buildx is not available"))
{
    logger.LogError(ex, "Install docker-buildx-plugin before building images.");
}

When it happens

Trigger: Calling BuildImageAsync on a Docker installation that lacks the buildx plugin: minimal docker CLI installs, older Docker Engine versions, distro-packaged docker.io without docker-buildx-plugin, or environments where the plugin is not on the CLI plugins path.

Common situations: Linux servers with docker.io from distro repos (buildx not bundled); slim CI images; Docker version < 19.03; manually installed docker CLI without plugins directory ($HOME/.docker/cli-plugins or /usr/local/lib/docker/cli-plugins).

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Docker build failed with exit code
• Failed to create buildkit instance
• ImageName must be provided in options.
• Invalid container image format
• OutputPath must be provided when ImageFormat is Oci.

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/75c7067707a2f4d2. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs:134

                    processResult.TotalProcessOutputLineCount);
            }
        }
        finally
        {
            // Clean up the buildkit instance if we created one
            if (!string.IsNullOrEmpty(builderName))
            {
                await RemoveBuildkitInstanceAsync(builderName, cancellationToken).ConfigureAwait(false);
            }
        }
    }

    public override async Task BuildImageAsync(string contextPath, string dockerfilePath, ContainerImageBuildOptions? options, Dictionary<string, string?> buildArguments, Dictionary<string, BuildImageSecretValue> buildSecrets, string? stage, CancellationToken cancellationToken)
    {
        // Verify buildx is available before attempting a Dockerfile build
        if (!await CheckDockerBuildxAsync(cancellationToken).ConfigureAwait(false))
        {
            throw new DistributedApplicationException(
                "Docker buildx is not available. Install the buildx plugin and try again.");
        }

        // Normalize the context path to handle trailing slashes and relative paths
        var normalizedContextPath = Path.GetFullPath(contextPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);

        await RunDockerBuildAsync(
            normalizedContextPath,
            dockerfilePath,
            options,
            buildArguments,
            buildSecrets,
            stage,
            cancellationToken).ConfigureAwait(false);
    }

    public override async Task<bool> CheckIfRunningAsync(CancellationToken cancellationToken)
    {

View on GitHub (pinned to 25830f84bd)