{"record":{"id":"75c7067707a2f4d2","repo":"microsoft/aspire","slug":"docker-buildx-is-not-available-install-the-buildx-plugin-and","errorCode":null,"errorMessage":"Docker buildx is not available. Install the buildx plugin and try again.","messagePattern":"Docker buildx is not available\\. Install the buildx plugin and try again\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs","lineNumber":134,"sourceCode":"                    processResult.TotalProcessOutputLineCount);\n            }\n        }\n        finally\n        {\n            // Clean up the buildkit instance if we created one\n            if (!string.IsNullOrEmpty(builderName))\n            {\n                await RemoveBuildkitInstanceAsync(builderName, cancellationToken).ConfigureAwait(false);\n            }\n        }\n    }\n\n    public override async Task BuildImageAsync(string contextPath, string dockerfilePath, ContainerImageBuildOptions? options, Dictionary<string, string?> buildArguments, Dictionary<string, BuildImageSecretValue> buildSecrets, string? stage, CancellationToken cancellationToken)\n    {\n        // Verify buildx is available before attempting a Dockerfile build\n        if (!await CheckDockerBuildxAsync(cancellationToken).ConfigureAwait(false))\n        {\n            throw new DistributedApplicationException(\n                \"Docker buildx is not available. Install the buildx plugin and try again.\");\n        }\n\n        // Normalize the context path to handle trailing slashes and relative paths\n        var normalizedContextPath = Path.GetFullPath(contextPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);\n\n        await RunDockerBuildAsync(\n            normalizedContextPath,\n            dockerfilePath,\n            options,\n            buildArguments,\n            buildSecrets,\n            stage,\n            cancellationToken).ConfigureAwait(false);\n    }\n\n    public override async Task<bool> CheckIfRunningAsync(CancellationToken cancellationToken)\n    {","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs#L116-L152","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Install the buildx plugin: 'docker buildx install' via package (apt install docker-buildx-plugin) or download the plugin binary into the CLI plugins directory.","Upgrade Docker Desktop / Docker Engine to a recent version that ships buildx.","Verify with 'docker buildx version' before running the app host.","Use a runtime that does not require buildx if the build features are not needed."],"exampleFix":"// before: docker.io installed on Ubuntu without buildx\nsudo apt-get install -y docker.io\n// after\nsudo apt-get install -y docker.io docker-buildx-plugin\ndocker buildx version","handlingStrategy":"validation","validationCode":"var probe = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(\"docker\", \"buildx version\") { RedirectStandardOutput = true, RedirectStandardError = true });\nprobe?.WaitForExit(5000);\nif (probe?.ExitCode != 0)\n{\n    throw new InvalidOperationException(\"docker buildx plugin is required for image builds.\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);\n}\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"buildx is not available\"))\n{\n    logger.LogError(ex, \"Install docker-buildx-plugin before building images.\");\n}","preventionTips":["Include docker-buildx-plugin in base images and CI setup steps.","Check 'docker buildx version' in environment preflight scripts.","Prefer official Docker installation channels over minimal distro packages."],"tags":["docker","buildx","image-build","missing-plugin"],"backgroundTag":"missing-dependency","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}