microsoft/aspire · error · ArgumentOutOfRangeException

ArgumentOutOfRangeException: Specified argument was out of…

Error message

ArgumentOutOfRangeException: Specified argument was out of range of valid values. (Parameter 'tool')

What it means

JavaBuildToolResolver.GetDefaultWrapperName maps (JavaBuildTool, isWindows) to the wrapper script name (mvnw/mvnw.cmd, gradlew/gradlew.bat) and throws ArgumentOutOfRangeException for any tool value outside Maven or Gradle. Like error 980, it is a defensive switch exhaustiveness guard against an unknown JavaBuildTool.

Solutions

Explicitly specify Maven or Gradle for the Java resource (e.g. via the build tool parameter of the AddJavaApp/With* APIs).
Validate incoming tool values with Enum.IsDefined before use.
Align package versions so JavaBuildTool and its resolvers match.

Example fix

// before
var wrapper = JavaBuildToolResolver.GetDefaultWrapperName(default, isWindows: false);
// after
var wrapper = JavaBuildToolResolver.GetDefaultWrapperName(JavaBuildTool.Gradle, isWindows: false);

Defensive patterns

Strategy: type-guard

Validate before calling

if (tool is not (JavaBuildTool.Maven or JavaBuildTool.Gradle)) throw new ArgumentException($"Unsupported JavaBuildTool: {tool}");
var wrapper = JavaBuildToolResolver.GetDefaultWrapperName(tool, OperatingSystem.IsWindows());

Type guard

static bool IsKnownJavaBuildTool(JavaBuildTool tool) => tool is JavaBuildTool.Maven or JavaBuildTool.Gradle;

Try / catch

try { var wrapper = JavaBuildToolResolver.GetDefaultWrapperName(tool, isWindows); } catch (ArgumentOutOfRangeException ex) { log.LogError(ex, "Cannot resolve wrapper for tool {Tool}", tool); }

Prevention

Pass Maven or Gradle explicitly when configuring Java resources.
Sanitize any enum value read from configuration or JSON before casting.
After upgrading Aspire.Hosting.Java, recompile so enum and resolvers match.

When it happens

Trigger: Passing default(JavaBuildTool), an int cast to JavaBuildTool outside the defined members, or a newly added enum member into the wrapper-name resolution path used when preparing wrapper-based launch commands.

Common situations: Config deserialization yields an invalid tool number; resource model built without specifying the tool; version skew between the enum definition and resolver code after a package upgrade.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/e034fd9275cd843d. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Java/JavaBuildToolResolver.cs:198

        {
            return new DirectoryInfo(path);
        }
        catch (Exception ex) when (ex is ArgumentException or PathTooLongException or NotSupportedException)
        {
            return null;
        }
    }

    /// <summary>
    /// Returns the conventional wrapper name for a build tool on the requested execution platform.
    /// </summary>
    internal static string GetDefaultWrapperName(JavaBuildTool tool, bool isWindows) => (tool, isWindows) switch
    {
        (JavaBuildTool.Maven, true) => "mvnw.cmd",
        (JavaBuildTool.Maven, false) => "mvnw",
        (JavaBuildTool.Gradle, true) => "gradlew.bat",
        (JavaBuildTool.Gradle, false) => "gradlew",
        _ => throw new ArgumentOutOfRangeException(nameof(tool), tool, null)
    };
}

View on GitHub (pinned to 25830f84bd)