microsoft/aspire · error · ProcessFailedException

Docker build failed with exit code

Error message

Docker build failed with exit code {processResult.ExitCode}.

What it means

After invoking 'docker build' (via buildx), Aspire checks the process exit code; a non-zero code means the build itself failed. The exception is a ProcessFailedException carrying the exit code plus the retained process output and line count so the caller can diagnose the underlying build failure.

Solutions

Read the ProcessOutput attached to the exception (or run with retainOutput/logging) to find the actual docker build error line.
Fix the Dockerfile error indicated (missing image, failing step, invalid instruction).
Ensure all required build arguments and secrets are supplied in buildArguments/buildSecrets.
Re-run 'docker buildx build ...' manually with the same arguments to reproduce locally.

Example fix

// before: dockerfile references ARG VERSION but no build arg is passed
RUN echo $VERSION
// after: supply the argument
await runtime.BuildImageAsync(ctx, dockerfile, new ContainerImageBuildOptions {
    ImageName = "app",
}, new Dictionary<string, string?> { ["VERSION"] = "1.0.0" }, new(), null, ct);

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate what you can before invoking docker build
if (!File.Exists(dockerfilePath)) throw new FileNotFoundException("Dockerfile not found", dockerfilePath);
if (!Directory.Exists(contextPath)) throw new DirectoryNotFoundException(contextPath);

Try / catch

try
{
    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);
}
catch (ProcessFailedException ex)
{
    logger.LogError(ex, "docker build failed (exit {Code}). Tail of output:\n{Output}",
        ex.ExitCode,
        string.Join('\n', ex.ProcessOutput.Split('\n').TakeLast(30)));
    throw;
}

Prevention

Always surface ProcessOutput on failure — the exit code alone is not diagnostic.
Test Dockerfiles independently with docker buildx build before wiring into automation.
Pin base image tags and provide all build args/secrets up front.

When it happens

Trigger: BuildImageAsync -> RunDockerBuildAsync executes the docker build command and the process exits non-zero for any build-level reason: Dockerfile errors, missing base image, failing RUN steps, invalid build args/secrets, context path problems, or buildx backend errors.

Common situations: Typo or syntax error in the Dockerfile; base image tag not found or requires auth; RUN step (dotnet restore, npm install) failing due to network or lock-file mismatch; build argument referenced in Dockerfile but not provided; disk space exhaustion.

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

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

Appendix: source

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

            {
                if (buildSecret.Value.Type == BuildImageSecretType.Environment && buildSecret.Value.Value is not null)
                {
                    environmentVariables[buildSecret.Key.ToUpperInvariant()] = buildSecret.Value.Value;
                }
            }

            var processResult = await ExecuteContainerCommandWithResultAsync(
                arguments,
                "Docker build for {ImageName} failed with exit code {ExitCode}.",
                "Docker build for {ImageName} succeeded.",
                cancellationToken,
                new object[] { imageName },
                environmentVariables,
                retainOutput: true).ConfigureAwait(false);

            if (processResult.ExitCode != 0)
            {
                throw new ProcessFailedException(
                    $"Docker build failed with exit code {processResult.ExitCode}.",
                    processResult.ExitCode,
                    processResult.ProcessOutput,
                    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)
    {

View on GitHub (pinned to 25830f84bd)