microsoft/aspire · error · ArgumentException

OutputPath must be provided when ImageFormat is Oci.

Error message

OutputPath must be provided when ImageFormat is Oci.

What it means

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.

Solutions

1. Set OutputPath on the options when choosing ImageFormat.Oci.
2. If you do not need OCI archive output, use ContainerImageFormat.Docker (or leave it null) so the image loads into the local store.
3. Validate options before the call: if ImageFormat is Oci, require a non-empty OutputPath.

Example fix

// before
var options = new ContainerImageBuildOptions { ImageName = "app", ImageFormat = ContainerImageFormat.Oci };
// after
var options = new ContainerImageBuildOptions { ImageName = "app", ImageFormat = ContainerImageFormat.Oci, OutputPath = "./artifacts" };

if (options?.ImageFormat == ContainerImageFormat.Oci && string.IsNullOrWhiteSpace(options.OutputPath))
{
    throw new ArgumentException("OutputPath is required when ImageFormat is Oci.", nameof(options));
}

bool IsValidForFormat(ContainerImageBuildOptions? o) =>
    o?.ImageFormat != ContainerImageFormat.Oci || !string.IsNullOrWhiteSpace(o.OutputPath);

try
{
    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);
}
catch (ArgumentException ex) when (ex.Message.Contains("OutputPath"))
{
    logger.LogError(ex, "OCI builds require an OutputPath.");
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ImageName must be provided in options.
• Docker build failed with exit code
• Docker buildx is not available. Install the buildx plugin…
• Failed to create buildkit instance
• Invalid container image format

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

Appendix: source

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

    protected override string RuntimeExecutable => KnownContainerRuntimes.Docker;
    public override string Name => "Docker";
    private async Task RunDockerBuildAsync(string contextPath, string dockerfilePath, ContainerImageBuildOptions? options, Dictionary<string, string?> buildArguments, Dictionary<string, BuildImageSecretValue> buildSecrets, string? stage, CancellationToken cancellationToken)
    {
        var imageName = !string.IsNullOrEmpty(options?.Tag)
            ? $"{options.ImageName}:{options.Tag}"
            : options?.ImageName ?? throw new ArgumentException("ImageName must be provided in options.", nameof(options));

        string? builderName = null;
        var resourceName = ResourceExtensions.FlattenContainerImageName(imageName);

        // Docker requires a custom buildkit instance for the image when
        // targeting the OCI format so we construct it and remove it here.
        if (options?.ImageFormat == ContainerImageFormat.Oci)
        {
            if (string.IsNullOrEmpty(options?.OutputPath))
            {
                throw new ArgumentException("OutputPath must be provided when ImageFormat is Oci.", nameof(options));
            }

            builderName = $"{resourceName}-builder";
            await CreateBuildkitInstanceAsync(builderName, cancellationToken).ConfigureAwait(false);
        }

        try
        {
            var arguments = $"buildx build --file \"{dockerfilePath}\" --tag \"{imageName}\"";

            // Use the specific builder for OCI builds
            if (!string.IsNullOrEmpty(builderName))
            {
                arguments += $" --builder \"{builderName}\"";
            }

            // Add platform support if specified
            if (options?.TargetPlatform is not null)

View on GitHub (pinned to 25830f84bd)