{"record":{"id":"2f74649e89da82d7","repo":"microsoft/aspire","slug":"docker-build-failed-with-exit-code-processresult-exitcode","errorCode":null,"errorMessage":"Docker build failed with exit code {processResult.ExitCode}.","messagePattern":"Docker build failed with exit code (.+?)\\.","errorType":"exception","errorClass":"ProcessFailedException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs","lineNumber":112,"sourceCode":"            {\n                if (buildSecret.Value.Type == BuildImageSecretType.Environment && buildSecret.Value.Value is not null)\n                {\n                    environmentVariables[buildSecret.Key.ToUpperInvariant()] = buildSecret.Value.Value;\n                }\n            }\n\n            var processResult = await ExecuteContainerCommandWithResultAsync(\n                arguments,\n                \"Docker build for {ImageName} failed with exit code {ExitCode}.\",\n                \"Docker build for {ImageName} succeeded.\",\n                cancellationToken,\n                new object[] { imageName },\n                environmentVariables,\n                retainOutput: true).ConfigureAwait(false);\n\n            if (processResult.ExitCode != 0)\n            {\n                throw new ProcessFailedException(\n                    $\"Docker build failed with exit code {processResult.ExitCode}.\",\n                    processResult.ExitCode,\n                    processResult.ProcessOutput,\n                    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    {","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: dockerfile references ARG VERSION but no build arg is passed\nRUN echo $VERSION\n// after: supply the argument\nawait runtime.BuildImageAsync(ctx, dockerfile, new ContainerImageBuildOptions {\n    ImageName = \"app\",\n}, new Dictionary<string, string?> { [\"VERSION\"] = \"1.0.0\" }, new(), null, ct);","handlingStrategy":"try-catch","validationCode":"// Pre-validate what you can before invoking docker build\nif (!File.Exists(dockerfilePath)) throw new FileNotFoundException(\"Dockerfile not found\", dockerfilePath);\nif (!Directory.Exists(contextPath)) throw new DirectoryNotFoundException(contextPath);","typeGuard":null,"tryCatchPattern":"try\n{\n    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);\n}\ncatch (ProcessFailedException ex)\n{\n    logger.LogError(ex, \"docker build failed (exit {Code}). Tail of output:\\n{Output}\",\n        ex.ExitCode,\n        string.Join('\\n', ex.ProcessOutput.Split('\\n').TakeLast(30)));\n    throw;\n}","preventionTips":["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."],"tags":["docker","image-build","process-failure","dockerfile"],"backgroundTag":"http-error-response","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"}