{"record":{"id":"7f539ae2dd15ce6a","repo":"microsoft/aspire","slug":"resourceannotationmutationbehavior-must-be-either-append-or","errorCode":null,"errorMessage":"ResourceAnnotationMutationBehavior must be either Append or Replace.","messagePattern":"ResourceAnnotationMutationBehavior must be either Append or Replace\\.","errorType":"exception","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/DistributedApplicationResourceBuilder.cs","lineNumber":22,"sourceCode":"using Aspire.Hosting.ApplicationModel;\n\nnamespace Aspire.Hosting;\n\ninternal sealed class DistributedApplicationResourceBuilder<T>(IDistributedApplicationBuilder applicationBuilder, T resource) : IResourceBuilder<T> where T : IResource\n{\n    public T Resource { get; } = resource;\n    public IDistributedApplicationBuilder ApplicationBuilder { get; } = applicationBuilder;\n\n    /// <inheritdoc />\n    public IResourceBuilder<T> WithAnnotation<TAnnotation>(TAnnotation annotation, ResourceAnnotationMutationBehavior behavior = ResourceAnnotationMutationBehavior.Append) where TAnnotation : IResourceAnnotation\n    {\n        ArgumentNullException.ThrowIfNull(annotation);\n\n        // Some defensive code to protect against introducing a new enumeration value without first updating\n        // this code to accommodate it.\n        if (behavior != ResourceAnnotationMutationBehavior.Append && behavior != ResourceAnnotationMutationBehavior.Replace)\n        {\n            throw new ArgumentOutOfRangeException(nameof(behavior), behavior, \"ResourceAnnotationMutationBehavior must be either Append or Replace.\");\n        }\n\n        // If the behavior is AddReplace then there should never be more than one annotation present. The following call will result in an exception which\n        // allows us to easily spot these bugs.\n        if (behavior == ResourceAnnotationMutationBehavior.Replace && Resource.Annotations.OfType<TAnnotation>().SingleOrDefault() is { } existingAnnotation)\n        {\n            Resource.Annotations.Remove(existingAnnotation);\n        }\n\n        Resource.Annotations.Add(annotation);\n        return this;\n    }\n}\n","sourceCodeStart":4,"sourceCodeEnd":36,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/DistributedApplicationResourceBuilder.cs#L4-L36","documentation":"DistributedApplicationResourceBuilder.WithAnnotation validates the ResourceAnnotationMutationBehavior argument and throws ArgumentOutOfRangeException when the value is neither Append nor Replace. This defensive check catches new enum members added without corresponding handling in the annotation mutation logic.","triggerScenarios":"Passing an invalid ResourceAnnotationMutationBehavior value to WithAnnotation<TAnnotation> — only possible with enum values outside Append/Replace (e.g. a cast of an arbitrary int, or code compiled against a newer enum version with extra members).","commonSituations":"Generic/reflective helper libraries that assign mutation behavior dynamically and pass raw enum values; binary-version mismatches where an extension compiled against a newer Aspire version passes an enum member the runtime's WithAnnotation doesn't accept; test code casting ints to the enum.","solutions":["Pass only ResourceAnnotationMutationBehavior.Append or ResourceAnnotationMutationBehavior.Replace to WithAnnotation.","Ensure all Aspire.Hosting packages are the same version so enum definitions and validation logic match.","If behavior comes from configuration/dynamic code, validate/whitelist it to the two supported values before calling."],"exampleFix":"// before\nbuilder.WithAnnotation(new MyAnnotation(), (ResourceAnnotationMutationBehavior)3);\n// after\nbuilder.WithAnnotation(new MyAnnotation(), ResourceAnnotationMutationBehavior.Replace);","handlingStrategy":"validation","validationCode":"if (behavior is not (ResourceAnnotationMutationBehavior.Append or ResourceAnnotationMutationBehavior.Replace))\n    throw new ArgumentOutOfRangeException(nameof(behavior));","typeGuard":"bool IsValidMutationBehavior(ResourceAnnotationMutationBehavior b) => b is ResourceAnnotationMutationBehavior.Append or ResourceAnnotationMutationBehavior.Replace;","tryCatchPattern":"try { builder.WithAnnotation(annotation, behavior); } catch (ArgumentOutOfRangeException) { /* fall back to Append */ }","preventionTips":["Never cast raw ints to ResourceAnnotationMutationBehavior.","Pin all Aspire.Hosting packages to the same version to avoid enum drift.","Use switch/if whitelisting before passing dynamically-chosen behaviors."],"tags":["annotations","enum","argument"],"backgroundTag":"argument-out-of-range","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"}