{"record":{"id":"5de8c6826806a39f","repo":"microsoft/aspire","slug":"outputpath-must-be-provided-when-imageformat-is-oci","errorCode":null,"errorMessage":"OutputPath must be provided when ImageFormat is Oci.","messagePattern":"OutputPath must be provided when ImageFormat is Oci\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs","lineNumber":37,"sourceCode":"\n    protected override string RuntimeExecutable => KnownContainerRuntimes.Docker;\n    public override string Name => \"Docker\";\n    private async Task RunDockerBuildAsync(string contextPath, string dockerfilePath, ContainerImageBuildOptions? options, Dictionary<string, string?> buildArguments, Dictionary<string, BuildImageSecretValue> buildSecrets, string? stage, CancellationToken cancellationToken)\n    {\n        var imageName = !string.IsNullOrEmpty(options?.Tag)\n            ? $\"{options.ImageName}:{options.Tag}\"\n            : options?.ImageName ?? throw new ArgumentException(\"ImageName must be provided in options.\", nameof(options));\n\n        string? builderName = null;\n        var resourceName = ResourceExtensions.FlattenContainerImageName(imageName);\n\n        // Docker requires a custom buildkit instance for the image when\n        // targeting the OCI format so we construct it and remove it here.\n        if (options?.ImageFormat == ContainerImageFormat.Oci)\n        {\n            if (string.IsNullOrEmpty(options?.OutputPath))\n            {\n                throw new ArgumentException(\"OutputPath must be provided when ImageFormat is Oci.\", nameof(options));\n            }\n\n            builderName = $\"{resourceName}-builder\";\n            await CreateBuildkitInstanceAsync(builderName, cancellationToken).ConfigureAwait(false);\n        }\n\n        try\n        {\n            var arguments = $\"buildx build --file \\\"{dockerfilePath}\\\" --tag \\\"{imageName}\\\"\";\n\n            // Use the specific builder for OCI builds\n            if (!string.IsNullOrEmpty(builderName))\n            {\n                arguments += $\" --builder \\\"{builderName}\\\"\";\n            }\n\n            // Add platform support if specified\n            if (options?.TargetPlatform is not null)","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Publishing/DockerContainerRuntime.cs#L19-L55","documentation":"When building an image in OCI format with Docker, Aspire uses a custom buildx builder and must export the image to a filesystem path. If ImageFormat is ContainerImageFormat.Oci but options.OutputPath is null or empty, RunDockerBuildAsync throws ArgumentException, because OCI output cannot be delivered to the local image store the way the Docker format can.","triggerScenarios":"Calling BuildImageAsync with options where ImageFormat == ContainerImageFormat.Oci and OutputPath is null or empty string. Docker format may tolerate a missing OutputPath, but OCI cannot.","commonSituations":"Switching ImageFormat to Oci for OCI-compliant archives without remembering the archive destination; configuration-driven formats where the OCI branch skips OutputPath population; migrating from Docker format builds to OCI builds.","solutions":["Set OutputPath on the options when choosing ImageFormat.Oci.","If you do not need OCI archive output, use ContainerImageFormat.Docker (or leave it null) so the image loads into the local store.","Validate options before the call: if ImageFormat is Oci, require a non-empty OutputPath."],"exampleFix":"// before\nvar options = new ContainerImageBuildOptions { ImageName = \"app\", ImageFormat = ContainerImageFormat.Oci };\n// after\nvar options = new ContainerImageBuildOptions { ImageName = \"app\", ImageFormat = ContainerImageFormat.Oci, OutputPath = \"./artifacts\" };","handlingStrategy":"validation","validationCode":"if (options?.ImageFormat == ContainerImageFormat.Oci && string.IsNullOrWhiteSpace(options.OutputPath))\n{\n    throw new ArgumentException(\"OutputPath is required when ImageFormat is Oci.\", nameof(options));\n}","typeGuard":"bool IsValidForFormat(ContainerImageBuildOptions? o) =>\n    o?.ImageFormat != ContainerImageFormat.Oci || !string.IsNullOrWhiteSpace(o.OutputPath);","tryCatchPattern":"try\n{\n    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);\n}\ncatch (ArgumentException ex) when (ex.Message.Contains(\"OutputPath\"))\n{\n    logger.LogError(ex, \"OCI builds require an OutputPath.\");\n}","preventionTips":["Treat OutputPath as mandatory whenever ImageFormat is Oci in your build pipeline.","Default ImageFormat to Docker unless you specifically need OCI archives.","Add a validation unit test for options combinations."],"tags":["docker","oci","image-build","argument-validation"],"backgroundTag":"missing-required-argument","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}