microsoft/aspire · error · ProcessFailedException

Failed to create buildkit instance

Error message

Failed to create buildkit instance '{builderName}' with exit code {processResult.ExitCode}.

What it means

For OCI-format builds, DockerContainerRuntime creates a dedicated buildx builder instance (CreateBuildkitInstanceAsync). If the 'docker buildx create' command exits non-zero, the runtime throws ProcessFailedException including the builder name, exit code, and retained process output.

Solutions

1. Check the ProcessOutput on the exception for the docker buildx create error message.
2. Ensure the Docker daemon is running ('docker info') before building.
3. Remove any conflicting builder: 'docker buildx rm <name>-builder' then retry.
4. Upgrade docker-buildx-plugin if the BuildKit instance creation is failing due to version incompatibility.

Example fix

// before: retry fails with stale builder of same name
// after: clean up builders before OCI build
docker buildx rm myapp-builder || true
docker builder prune -f

var info = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo("docker", "info") { RedirectStandardOutput = true });
if (info is null || !info.WaitForExit(5000) || info.ExitCode != 0)
{
    throw new InvalidOperationException("Docker daemon is not reachable; buildkit instance creation will fail.");
}

try
{
    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);
}
catch (ProcessFailedException ex) when (ex.Message.Contains("buildkit instance"))
{
    logger.LogError(ex, "Buildkit creation failed:\n{Output}", ex.ProcessOutput);
    throw;
}

When it happens

Trigger: RunDockerBuildAsync with ImageFormat == Oci triggers CreateBuildkitInstanceAsync; the underlying 'docker buildx create' process exits non-zero due to daemon unavailability, invalid builder name, buildx/BuildKit incompatibility, or permissions issues talking to the Docker daemon.

Common situations: Docker daemon not running while buildx plugin check passed; containerd storage/snapshotter conflicts; restricted CI environments blocking builder creation; stale/corrupt builder state with the same name.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Docker build failed with exit code
• Docker buildx is not available. Install the buildx plugin…
• 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/0c30608740f9747c. Report an issue: GitHub.

Appendix: source

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

        {
            return false;
        }
    }

    private async Task CreateBuildkitInstanceAsync(string builderName, CancellationToken cancellationToken)
    {
        var arguments = $"buildx create --name \"{builderName}\" --driver docker-container";
        var processResult = await ExecuteContainerCommandWithResultAsync(
            arguments,
            "Failed to create buildkit instance {BuilderName} with exit code {ExitCode}.",
            "Successfully created buildkit instance {BuilderName}.",
            cancellationToken,
            new object[] { builderName },
            retainOutput: true).ConfigureAwait(false);

        if (processResult.ExitCode != 0)
        {
            throw new ProcessFailedException(
                $"Failed to create buildkit instance '{builderName}' with exit code {processResult.ExitCode}.",
                processResult.ExitCode,
                processResult.ProcessOutput,
                processResult.TotalProcessOutputLineCount);
        }
    }

    private async Task<int> RemoveBuildkitInstanceAsync(string builderName, CancellationToken cancellationToken)
    {
        var arguments = $"buildx rm \"{builderName}\"";

        return await ExecuteContainerCommandWithExitCodeAsync(
            arguments,
            "Failed to remove buildkit instance {BuilderName} with exit code {ExitCode}.",
            "Successfully removed buildkit instance {BuilderName}.",
            cancellationToken,
            new object[] { builderName }).ConfigureAwait(false);
    }

View on GitHub (pinned to 25830f84bd)