microsoft/aspire · error · ArgumentException

ImageName must be provided in options.

Error message

ImageName must be provided in options.

What it means

DockerContainerRuntime.BuildImageAsync ultimately needs an image name to tag and build. When the options object is supplied but its ImageName is null or empty (and no Tag alternative exists), RunDockerBuildAsync throws ArgumentException naming the 'options' parameter. This is a defensive guard against callers constructing ContainerImageBuildOptions without the required image name.

Solutions

1. Set ImageName on the ContainerImageBuildOptions before calling BuildImageAsync.
2. Validate the options object at construction time (required property) so it cannot be created without ImageName.
3. Check the upstream source of the image name (resource name, config) for null/empty values and fix that.

Example fix

// before
var options = new ContainerImageBuildOptions { Tag = "v1" };
// after
var options = new ContainerImageBuildOptions { ImageName = "myapp/api", Tag = "v1" };

if (options is null || string.IsNullOrWhiteSpace(options.ImageName))
{
    throw new ArgumentException("ImageName must be set before building an image.", nameof(options));
}

bool HasImageName(ContainerImageBuildOptions? o) => !string.IsNullOrWhiteSpace(o?.ImageName);

try
{
    await runtime.BuildImageAsync(ctx, dockerfile, options, args, secrets, stage, ct);
}
catch (ArgumentException ex) when (ex.ParamName == "options")
{
    logger.LogError(ex, "Image build options are incomplete: {Message}", ex.Message);
}

When it happens

Trigger: Calling BuildImageAsync (via DockerContainerRuntime) with a ContainerImageBuildOptions instance whose ImageName is null/empty — e.g. new ContainerImageBuildOptions { Tag = "v1" } without ImageName, since even a Tag produces "$null:v1" and falls through to the ImageName check.

Common situations: Programmatically building options where the image name comes from a nullable resource property or config value that was not populated; copying sample code and omitting ImageName; refactors that rename the image-name property leaving the assignment dropped.

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

• OutputPath must be provided when ImageFormat is Oci.
• 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/b7dbfab10b17ba3b. Report an issue: GitHub.

Appendix: source

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

using Aspire.Hosting.Dcp.Process;
using Aspire.Shared;
using Microsoft.Extensions.Logging;

namespace Aspire.Hosting.Publishing;

internal sealed class DockerContainerRuntime : ContainerRuntimeBase<DockerContainerRuntime>
{
    public DockerContainerRuntime(ILogger<DockerContainerRuntime> logger, IProcessRunner processRunner) : base(logger, processRunner)
    {
    }

    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

View on GitHub (pinned to 25830f84bd)