microsoft/aspire · error · ArgumentOutOfRangeException

Tag conflicts with digest provided on the 'image' parameter

Error message

Tag conflicts with digest provided on the 'image' parameter

What it means

WithImage throws ArgumentOutOfRangeException when the tag parameter is supplied but the image reference contains a digest (e.g. image@sha256:...). A tag and a digest are mutually exclusive ways to pin an image, so the library rejects the combination, naming the conflicting tag parameter.

Solutions

Remove the tag parameter and rely solely on the digest in the image reference.
Or pin by tag instead: remove the @sha256: digest from the image string and pass the tag parameter.
Use WithImageSHA256 afterward if you want to attach a digest to a tag-based reference.
exampleFix placeholder

Example fix

// before
.WithImage("myrepo/myapp@sha256:abc123", tag: "v1");
// after
.WithImage("myrepo/myapp@sha256:abc123");

Defensive patterns

Strategy: validation

Validate before calling

var parsed = ContainerReferenceParser.Parse(image);
if (tag is not null && parsed.Digest is not null)
    throw new ArgumentException("Cannot combine a tag parameter with a digest-pinned image reference.");

Try / catch

try
{
    resource.WithImage(image, tag);
}
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "tag")
{
    // Drop either the digest or the tag and retry
}

Prevention

Decide upfront whether to pin by tag or by digest — never both.
When moving to digest pinning, remove tag parameters from builder chains.
Use WithImageSHA256 to attach a digest to tag-based references instead of inlining '@sha256:'.

When it happens

Trigger: Calling WithImage("myrepo/myapp@sha256:abc...", tag: "v1") — a digest-bearing image plus an explicit tag argument.

Common situations: Pinning images by digest for reproducible builds while a templating layer also injects a tag; migrating configuration from tag-based to digest-based references without removing the tag.

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/46fb38598c59462a. Report an issue: GitHub.

Appendix: source

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

    /// <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
        {
            imageAnnotation = new ContainerImageAnnotation { Image = parsedRegistryAndImage };
            builder.Resource.Annotations.Add(imageAnnotation);
        }

        if (parsedReference.Digest is { })

View on GitHub (pinned to 25830f84bd)