{"record":{"id":"37314f5492b2eff0","repo":"microsoft/aspire","slug":"argumentoutofrangeexception-specified-argument-was-out-of-37314f","errorCode":null,"errorMessage":"ArgumentOutOfRangeException: Specified argument was out of range of valid values. (Parameter 'tool')","messagePattern":"ArgumentOutOfRangeException: Specified argument was out of range of valid values\\. \\(Parameter 'tool'\\)","errorType":"exception","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Java/JavaHostingExtensions.cs","lineNumber":1584,"sourceCode":"        builder.WithAnnotation(new JavaWrapperValidationAnnotation(tool));\n\n        return builder.OnBeforeResourceStarted((resource, _, _) =>\n        {\n            ValidateWrapperExists(resource, tool);\n            return Task.CompletedTask;\n        });\n    }\n\n    /// <summary>\n    /// The command that adds a wrapper to an existing project, named in the error raised when one is missing.\n    /// </summary>\n    internal static string GenerateWrapperCommand(JavaBuildTool tool) => tool switch\n    {\n        // -N keeps the goal from recursing into the modules of a multi-module build, which would litter\n        // every module with a wrapper that only the root needs.\n        JavaBuildTool.Maven => \"'mvn -N wrapper:wrapper'\",\n        JavaBuildTool.Gradle => \"'gradle wrapper'\",\n        _ => throw new ArgumentOutOfRangeException(nameof(tool), tool, null)\n    };\n\n    /// <summary>\n    /// Appends <paramref name=\"values\"/> to the <c>JAVA_TOOL_OPTIONS</c> environment variable, preserving\n    /// whatever is already there.\n    /// </summary>\n    /// <remarks>\n    /// The existing value may be any expression Aspire supports — a plain string, a\n    /// <see cref=\"ReferenceExpression\"/>, a parameter, or an endpoint reference — so a non-string value is\n    /// folded into a new <see cref=\"ReferenceExpression\"/> rather than being read as a string. An earlier\n    /// string-only implementation silently discarded non-string values.\n    /// </remarks>\n    private static void AppendJavaToolOptions(Dictionary<string, object> environmentVariables, string[] values)\n    {\n        var appended = string.Join(' ', values.Select(QuoteIfNeeded));\n\n        if (!environmentVariables.TryGetValue(JavaToolOptions, out var existing) || existing is null)\n        {","sourceCodeStart":1566,"sourceCodeEnd":1602,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L1566-L1602","documentation":"GenerateWrapperCommand maps a JavaBuildTool enum value to the wrapper-generation command string. The library throws ArgumentOutOfRangeException when the tool value is not Maven or Gradle, i.e. an undefined or future enum member reached this switch, so it fails fast instead of producing a broken command.","triggerScenarios":"Calling an API that accepts a JavaBuildTool (e.g. AddJavaApp/Maven/Gradle wrapper generation paths) with a JavaBuildTool value other than Maven or Gradle, typically via an unsafe cast or a stale compiled assembly after the enum gained new members.","commonSituations":"Casting an int or string parsed from config into JavaBuildTool without validating it; running an old Aspire.Hosting.Java binary against newer code that added an enum member; typos in custom tooling that constructs the enum.","solutions":["Pass only JavaBuildTool.Maven or JavaBuildTool.Gradle to the hosting API.","Validate the enum with Enum.IsDefined before casting from int/string config values.","Rebuild and redeploy all assemblies together so the enum and its consumers match versions.","If adding a new JavaBuildTool member, update GenerateWrapperCommand's switch expression."],"exampleFix":"// before\nvar tool = (JavaBuildTool)42;\nbuilder.AddJavaApp(\"svc\", ...\n// after\nvar raw = 42;\nvar tool = Enum.IsDefined(typeof(JavaBuildTool), raw) ? (JavaBuildTool)raw : throw new ArgumentException($\"Unknown build tool: {raw}\");","handlingStrategy":"validation","validationCode":"if (!Enum.IsDefined(typeof(JavaBuildTool), tool)) throw new ArgumentException($\"Unsupported JavaBuildTool: {tool}\");","typeGuard":"static bool IsValidJavaBuildTool(JavaBuildTool tool) => Enum.IsDefined(tool);","tryCatchPattern":"try { builder.AddJavaApp(...); } catch (ArgumentOutOfRangeException ex) when (ex.ParamName == \"tool\") { /* map to user-facing config error */ }","preventionTips":["Never cast raw ints/strings to JavaBuildTool without Enum.IsDefined/Enum.TryParse","Keep all NuGet package versions aligned when upgrading Aspire","Use switch expressions with no discard arm so the compiler forces exhaustive handling"],"tags":["argument-exception","enum","java","dotnet"],"backgroundTag":"invalid-enum-value","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}