{"record":{"id":"46fb38598c59462a","repo":"microsoft/aspire","slug":"tag-conflicts-with-digest-provided-on-the-image-parameter","errorCode":null,"errorMessage":"Tag conflicts with digest provided on the 'image' parameter","messagePattern":"Tag conflicts with digest provided on the 'image' parameter","errorType":"exception","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs","lineNumber":427,"sourceCode":"    /// <param name=\"tag\">Tag value.</param>\n    /// <returns>The <see cref=\"IResourceBuilder{T}\"/>.</returns>\n    /// <ats-returns>The resource builder.</ats-returns>\n    [AspireExport]\n    public static IResourceBuilder<T> WithImage<T>(this IResourceBuilder<T> builder, string image, string? tag = null) where T : ContainerResource\n    {\n        ArgumentNullException.ThrowIfNull(builder);\n        ArgumentNullException.ThrowIfNull(image);\n\n        var parsedReference = ContainerReferenceParser.Parse(image);\n\n        if (tag is { } && parsedReference.Tag is { })\n        {\n            throw new InvalidOperationException(\"Ambiguous tags - a tag was provided on both the 'tag' and 'image' parameters\");\n        }\n\n        if (tag is { } && parsedReference.Digest is { })\n        {\n            throw new ArgumentOutOfRangeException(nameof(tag), \"Tag conflicts with digest provided on the 'image' parameter\");\n        }\n\n        // For continuity with 9.0 and earlier behaviour, keep the registry and image combined.\n        var parsedRegistryAndImage = parsedReference.Registry is { }\n            ? $\"{parsedReference.Registry}/{parsedReference.Image}\"\n            : parsedReference.Image;\n\n        if (builder.Resource.Annotations.OfType<ContainerImageAnnotation>().LastOrDefault() is { } imageAnnotation)\n        {\n            imageAnnotation.Image = parsedRegistryAndImage;\n        }\n        else\n        {\n            imageAnnotation = new ContainerImageAnnotation { Image = parsedRegistryAndImage };\n            builder.Resource.Annotations.Add(imageAnnotation);\n        }\n\n        if (parsedReference.Digest is { })","sourceCodeStart":409,"sourceCodeEnd":445,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L409-L445","documentation":"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.","triggerScenarios":"Calling WithImage(\"myrepo/myapp@sha256:abc...\", tag: \"v1\") — a digest-bearing image plus an explicit tag argument.","commonSituations":"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.","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"],"exampleFix":"// before\n.WithImage(\"myrepo/myapp@sha256:abc123\", tag: \"v1\");\n// after\n.WithImage(\"myrepo/myapp@sha256:abc123\");","handlingStrategy":"validation","validationCode":"var parsed = ContainerReferenceParser.Parse(image);\nif (tag is not null && parsed.Digest is not null)\n    throw new ArgumentException(\"Cannot combine a tag parameter with a digest-pinned image reference.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    resource.WithImage(image, tag);\n}\ncatch (ArgumentOutOfRangeException ex) when (ex.ParamName == \"tag\")\n{\n    // Drop either the digest or the tag and retry\n}","preventionTips":["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:'."],"tags":["container-image","digest","tag","aspire"],"backgroundTag":"conflicting-config-options","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}