{"record":{"id":"69af5158b36e9059","repo":"microsoft/aspire","slug":"ambiguous-tags-a-tag-was-provided-on-both-the-tag-and-image","errorCode":null,"errorMessage":"Ambiguous tags - a tag was provided on both the 'tag' and 'image' parameters","messagePattern":"Ambiguous tags - a tag was provided on both the 'tag' and 'image' parameters","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs","lineNumber":422,"sourceCode":"    /// Allows overriding the image on a container.\n    /// </summary>\n    /// <typeparam name=\"T\">Type of container resource.</typeparam>\n    /// <param name=\"builder\">Builder for the container resource.</param>\n    /// <param name=\"image\">Image value.</param>\n    /// <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        {","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ContainerResourceBuilderExtensions.cs#L404-L440","documentation":"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.","triggerScenarios":"Calling WithImage(\"myrepo/myapp:1.0\", tag: \"2.0\") — a tag present in both the image reference and the tag parameter.","commonSituations":"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.","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"],"exampleFix":"// before\nbuilder.AddContainer(\"app\", \"image\").WithImage(\"myrepo/myapp:1.0\", tag: \"2.0\");\n// after\nbuilder.AddContainer(\"app\", \"image\").WithImage(\"myrepo/myapp\", tag: \"2.0\");","handlingStrategy":"validation","validationCode":"var parsed = ContainerReferenceParser.Parse(image);\nif (tag is not null && parsed.Tag is not null)\n    throw new InvalidOperationException(\"Specify the tag either in the image reference or the tag parameter, not both.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    resource.WithImage(image, tag);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Ambiguous tags\"))\n{\n    // Strip the tag from image or from tag parameter and retry\n}","preventionTips":["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."],"tags":["container-image","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"}