microsoft/aspire · error · InvalidOperationException

Ambiguous tags - a tag was provided on both the 'tag' and…

Error message

Ambiguous tags - a tag was provided on both the 'tag' and 'image' parameters

What it means

WithImage accepts an optional separate tag parameter alongside the image reference. If the image string itself already contains a tag (after parsing with ContainerReferenceParser) and a tag parameter is also supplied, the intent is ambiguous and this InvalidOperationException is thrown.

Solutions

Remove the tag from the image string and pass it only via the tag parameter, e.g. WithImage("myrepo/myapp", tag: "2.0").
Or remove the tag parameter and keep the tag inside the image reference.
Programmatically strip the tag (or check ContainerReferenceParser results) before composing the call.
exampleFix placeholder

Example fix

// before
builder.AddContainer("app", "image").WithImage("myrepo/myapp:1.0", tag: "2.0");
// after
builder.AddContainer("app", "image").WithImage("myrepo/myapp", tag: "2.0");

Defensive patterns

Strategy: validation

Validate before calling

var parsed = ContainerReferenceParser.Parse(image);
if (tag is not null && parsed.Tag is not null)
    throw new InvalidOperationException("Specify the tag either in the image reference or the tag parameter, not both.");

Try / catch

try
{
    resource.WithImage(image, tag);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Ambiguous tags"))
{
    // Strip the tag from image or from tag parameter and retry
}

Prevention

Keep the tag in exactly one place: either the image reference or the tag parameter.
Parse the image with ContainerReferenceParser before appending tags in templating code.
Avoid copying fully-qualified registry references directly into WithImage when also passing a tag.

When it happens

Trigger: Calling WithImage("myrepo/myapp:1.0", tag: "2.0") — a tag present in both the image reference and the tag parameter.

Common situations: Combining a fully-qualified image string (copied from a registry) with an explicit tag argument; templating code that appends a tag without checking whether the base image already has one.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

    /// Allows overriding the image on a container.
    /// </summary>
    /// <typeparam name="T">Type of container resource.</typeparam>
    /// <param name="builder">Builder for the container resource.</param>
    /// <param name="image">Image value.</param>
    /// <param name="tag">Tag value.</param>
    /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport]
    public static IResourceBuilder<T> WithImage<T>(this IResourceBuilder<T> builder, string image, string? tag = null) where T : ContainerResource
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(image);

        var parsedReference = ContainerReferenceParser.Parse(image);

        if (tag is { } && parsedReference.Tag is { })
        {
            throw new InvalidOperationException("Ambiguous tags - a tag was provided on both the 'tag' and 'image' parameters");
        }

        if (tag is { } && parsedReference.Digest is { })
        {
            throw new ArgumentOutOfRangeException(nameof(tag), "Tag conflicts with digest provided on the 'image' parameter");
        }

        // For continuity with 9.0 and earlier behaviour, keep the registry and image combined.
        var parsedRegistryAndImage = parsedReference.Registry is { }
            ? $"{parsedReference.Registry}/{parsedReference.Image}"
            : parsedReference.Image;

        if (builder.Resource.Annotations.OfType<ContainerImageAnnotation>().LastOrDefault() is { } imageAnnotation)
        {
            imageAnnotation.Image = parsedRegistryAndImage;
        }
        else
        {

View on GitHub (pinned to 25830f84bd)