{"record":{"id":"cc5dcb09599717a2","repo":"microsoft/aspire","slug":"argumentoutofrangeexception-specified-argument-was-out-of","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/JavaBuildToolAnnotation.cs","lineNumber":78,"sourceCode":"/// </remarks>\n/// <param name=\"MavenBuildArgs\">Arguments that package the application with Maven.</param>\n/// <param name=\"MavenLaunchArgs\">Arguments that launch the application with Maven.</param>\n/// <param name=\"GradleBuildArgs\">Arguments that package the application with Gradle.</param>\n/// <param name=\"GradleLaunchArgs\">Arguments that launch the application with Gradle.</param>\ninternal sealed record JavaDetectedBuildToolAnnotation(\n    string[] MavenBuildArgs,\n    string[] MavenLaunchArgs,\n    string[] GradleBuildArgs,\n    string[] GradleLaunchArgs) : IResourceAnnotation\n{\n    /// <summary>\n    /// Returns the build and launch arguments for <paramref name=\"tool\"/>.\n    /// </summary>\n    internal (string[] BuildArgs, string[] LaunchArgs) GetConfiguration(JavaBuildTool tool) => tool switch\n    {\n        JavaBuildTool.Maven => (MavenBuildArgs, MavenLaunchArgs),\n        JavaBuildTool.Gradle => (GradleBuildArgs, GradleLaunchArgs),\n        _ => throw new ArgumentOutOfRangeException(nameof(tool), tool, null)\n    };\n}\n\n/// <summary>\n/// Records the OpenTelemetry Java agent configured by <c>WithOtelAgent</c>.\n/// </summary>\n/// <remarks>\n/// The environment variable alone is not enough to reproduce the agent in a container. A relative agent\n/// path names a file produced by the build, which only exists in the Dockerfile's build stage, so the\n/// runtime stage has to copy it forward and the environment variable has to point at where it landed.\n/// Without this the published container starts a JVM pointing at an agent JAR that is not in the image\n/// and dies during VM initialization.\n/// </remarks>\n/// <param name=\"AgentPath\">\n/// The agent path exactly as authored, before any resolution, or <see langword=\"null\"/> when the caller\n/// asked for the location the build tool writes the agent to. That location is resolved on demand rather\n/// than when the annotation is added, so <c>WithOtelAgent()</c> and <c>WithMavenBuild()</c> can be called\n/// in either order.","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Java/JavaBuildToolAnnotation.cs#L60-L96","documentation":"JavaBuildToolAnnotation.GetConfiguration maps a JavaBuildTool enum to build/launch argument arrays and throws ArgumentOutOfRangeException when the value is neither Maven nor Gradle. This is the annotation layer's guard against an unknown or default(JavaBuildTool) value, since the enum only defines those two tools. It means the annotation was constructed or queried with an unrecognized build tool.","triggerScenarios":"Calling GetConfiguration with JavaBuildTool enum value outside {Maven, Gradle}, e.g. default(JavaBuildTool) (which is 0 and not Maven/Gradle if Maven is not 0), a cast of an arbitrary int to JavaBuildTool, or a new enum member added upstream without updating this switch.","commonSituations":"Deserializing a JavaBuildTool from config or JSON into an out-of-range numeric value; binding resource settings where the tool field was left unset; a newer Aspire version adding a JavaBuildTool member consumed by an older annotation switch (or vice versa).","solutions":["Set an explicit JavaBuildTool.Maven or JavaBuildTool.Gradle when configuring the Java resource instead of relying on an uninitialized enum value.","If the value comes from configuration/JSON, validate it against Enum.IsDefined(typeof(JavaBuildTool), value) before casting.","Upgrade the Aspire.Hosting.Java package so the enum and the switch are from the same version."],"exampleFix":"// before\nvar tool = default(JavaBuildTool);\nvar (buildArgs, launchArgs) = annotation.GetConfiguration(tool);\n// after\nvar tool = JavaBuildTool.Maven;\nvar (buildArgs, launchArgs) = annotation.GetConfiguration(tool);","handlingStrategy":"type-guard","validationCode":"if (!Enum.IsDefined(typeof(JavaBuildTool), tool)) throw new ArgumentException($\"Unsupported JavaBuildTool: {tool}\");\nvar (buildArgs, launchArgs) = annotation.GetConfiguration(tool);","typeGuard":"static bool IsKnownJavaBuildTool(JavaBuildTool tool) => tool is JavaBuildTool.Maven or JavaBuildTool.Gradle;","tryCatchPattern":"try { var cfg = annotation.GetConfiguration(tool); } catch (ArgumentOutOfRangeException ex) { log.LogError(ex, \"Unknown Java build tool {Tool}\", tool); }","preventionTips":["Always set the build tool explicitly rather than relying on default(JavaBuildTool).","Validate deserialized enum values with Enum.IsDefined before use.","Keep enum definitions and consuming switches in the same package version."],"tags":["java","enum","argument-out-of-range","build-tool"],"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"}