microsoft/aspire · error · ArgumentException

At least one of or must be specified.

Error message

At least one of {nameof(buildImage)} or {nameof(runtimeImage)} must be specified.

What it means

WithDockerfileBaseImage lets you override the base image in the build stage and/or the final runtime stage of a Dockerfile via a DockerfileBaseImageAnnotation. Calling it with both parameters null leaves nothing to override, so ArgumentException is thrown immediately.

Solutions

  1. Pass at least one non-null image name, e.g. .WithDockerfileBaseImage(buildImage: "mcr.microsoft.com/dotnet/sdk:10.0")
  2. Guard in wrapper code: only call WithDockerfileBaseImage when at least one image is resolved
  3. Provide a default runtime image when the build image is unavailable

Example fix

// before
var build = cfg["BuildImage"];
var runtime = cfg["RuntimeImage"]; // both null
builder.WithDockerfileBaseImage(build, runtime);
// after
if (build is not null || runtime is not null)
{
    builder.WithDockerfileBaseImage(build, runtime);
}
Defensive patterns

Strategy: validation

Validate before calling

if (buildImage is null && runtimeImage is null)
    throw new ArgumentException("At least one of buildImage/runtimeImage is required.");
builder.WithDockerfileBaseImage(buildImage, runtimeImage);

Try / catch

try { builder.WithDockerfileBaseImage(build, runtime); }
catch (ArgumentException ex) when (ex.ParamName == "buildImage") { /* provide a default image */ }

Prevention

When it happens

Trigger: Calling .WithDockerfileBaseImage() with no arguments; passing null variables for both buildImage and runtimeImage, e.g. values read from config that were absent.

Common situations: Making both images configurable from settings where neither key is set; refactoring away one of the two parameters and dropping the other; a helper wrapper forwarding nullable options without a default.

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

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

Appendix: source

Thrown at src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs:1849

    ///
    /// builder.AddPythonApp("myapp", "path/to/app", "main.py")
    ///        .WithDockerfileBaseImage(
    ///            buildImage: "ghcr.io/astral-sh/uv:python3.12-bookworm-slim",
    ///            runtimeImage: "python:3.12-slim-bookworm");
    ///
    /// builder.Build().Run();
    /// </code>
    /// </example>
    /// </remarks>
    [AspireExport]
    [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    public static IResourceBuilder<T> WithDockerfileBaseImage<T>(this IResourceBuilder<T> builder, string? buildImage = null, string? runtimeImage = null) where T : IResource
    {
        ArgumentNullException.ThrowIfNull(builder);

        if (buildImage is null && runtimeImage is null)
        {
            throw new ArgumentException($"At least one of {nameof(buildImage)} or {nameof(runtimeImage)} must be specified.", nameof(buildImage));
        }

        return builder.WithAnnotation(new DockerfileBaseImageAnnotation
        {
            BuildImage = buildImage,
            RuntimeImage = runtimeImage
        }, ResourceAnnotationMutationBehavior.Replace);
    }

    /// <summary>
    /// Adds a network alias to container resource.
    /// </summary>
    /// <typeparam name="T">The type of container resource.</typeparam>
    /// <param name="builder">The resource builder for the container resource.</param>
    /// <param name="alias">The network alias for the container.</param>
    /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    /// <remarks>

View on GitHub (pinned to 25830f84bd)