microsoft/aspire · error · ArgumentOutOfRangeException

The inspect mode must be a defined DenoInspectMode value.

Error message

The inspect mode must be a defined DenoInspectMode value.

What it means

WithDenoInspect validates that the DenoInspectMode is a defined enum member before storing it on the annotation, since the mode is translated into '--inspect' / '--inspect-brk[=host:port]' arguments at launch. An undefined value would render an invalid flag, so it throws ArgumentOutOfRangeException.

Solutions

Use DenoInspectMode.Inspect or DenoInspectMode.InspectBrk (or the overload default).
Validate with Enum.IsDefined before casting config input.
Rebuild with matching Aspire.Hosting.JavaScript versions.
Extend the flag-generation mapping in the library when adding new modes.

Example fix

// before
var mode = (DenoInspectMode)Enum.Parse(typeof(DenoInspectMode), config, ignoreCase: true);
resource.WithDenoInspect(mode);
// after
if (!Enum.TryParse<DenoInspectMode>(config, ignoreCase: true, out var mode) || !Enum.IsDefined(mode))
    throw new ArgumentException($"Unknown inspect mode '{config}'.");
resource.WithDenoInspect(mode);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(DenoInspectMode), mode)) throw new ArgumentException("mode must be a defined DenoInspectMode");

Type guard

static bool IsValidInspectMode(DenoInspectMode m) => Enum.IsDefined(m);

Try / catch

try { resource.WithDenoInspect(mode); } catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "mode") { /* fall back to DenoInspectMode.Inspect */ }

Prevention

Parse enums with TryParse + IsDefined
Avoid numeric enum literals in configuration
Keep package versions in sync

When it happens

Trigger: Calling WithDenoInspect with a mode cast from an int/string that is not a defined DenoInspectMode (Inspect/InspectBrk), typically from config parsing or version-mismatched assemblies.

Common situations: Mapping debugger settings strings to the enum with direct casts; stale builds after enum changes; custom tooling constructing the enum numerically.

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/c64bd95dc38eae7d. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.JavaScript/DenoHostingExtensions.cs:318

    /// <summary>Enables a Deno inspector mode, optionally at <paramref name="hostPort"/> (for example <c>127.0.0.1:9229</c>).</summary>
    /// <param name="builder">The Deno app resource builder.</param>
    /// <param name="mode">The inspector mode to enable.</param>
    /// <param name="hostPort">The optional inspector host:port value.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    /// <exception cref="ArgumentOutOfRangeException">Thrown when <paramref name="mode"/> is not a defined <see cref="DenoInspectMode"/> value.</exception>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport]
    [Experimental("ASPIREDENO001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    public static IResourceBuilder<DenoAppResource> WithDenoInspect(
        this IResourceBuilder<DenoAppResource> builder,
        DenoInspectMode mode = DenoInspectMode.Inspect,
        string? hostPort = null)
    {
        ArgumentNullException.ThrowIfNull(builder);
        if (!Enum.IsDefined(mode))
        {
            throw new ArgumentOutOfRangeException(nameof(mode), mode, "The inspect mode must be a defined DenoInspectMode value.");
        }

        var annotation = GetOrAddDenoAnnotation(builder);
        annotation.Inspect = mode;
        annotation.InspectHostPort = string.IsNullOrEmpty(hostPort) ? null : hostPort;
        return builder;
    }

    // ---- Modes ------------------------------------------------------------------------------

    /// <summary>Selects the <c>deno run &lt;entrypoint&gt;</c> mode (the default).</summary>
    /// <param name="builder">The Deno app resource builder.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport]
    [Experimental("ASPIREDENO001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    public static IResourceBuilder<DenoAppResource> WithDenoRun(this IResourceBuilder<DenoAppResource> builder)
    {

View on GitHub (pinned to 25830f84bd)