microsoft/aspire · error · ArgumentException

Qualified Deno unstable flags must start with "--unstable-".

Error message

Qualified Deno unstable flags must start with "--unstable-".

What it means

WithDenoUnstable accepts either bare feature names ('foo' -> '--unstable-foo') or fully qualified flags ('--unstable-foo'). If a value starts with '--' but is not prefixed with '--unstable-', the library cannot safely normalize it and throws ArgumentException, since Deno would receive an unrelated flag.

Solutions

1. Pass bare feature names: WithDenoUnstable("kv", "cron") instead of "--unstable-kv".
2. If passing qualified flags, ensure each starts exactly with "--unstable-".
3. Move non-unstable flags to WithDenoRuntimeArgs instead.
4. Trim or validate the config list so generic '--' flags are routed to the right API.

Example fix

// before
resource.WithDenoUnstable("--sloppy-imports");
// after
resource.WithDenoUnstable("sloppy-imports");

if (features.Any(f => f.StartsWith("--") && !f.StartsWith("--unstable-"))) throw new ArgumentException("Unstable flags must be bare names or start with '--unstable-'.");

static bool IsValidUnstableFlag(string f) => !f.StartsWith("--") || f.StartsWith("--unstable-");

try { resource.WithDenoUnstable(features); } catch (ArgumentException ex) when (ex.ParamName == "features") { /* strip/rename offending flags */ }

When it happens

Trigger: Calling WithDenoUnstable("--allow-net") or any '--xyz' value lacking the '--unstable-' prefix; mixing other Deno flags into the unstable-features list.

Common situations: Copying a full Deno command line into WithDenoUnstable; config that stores complete flags rather than feature names; confusion between runtime args (WithDenoRuntimeArgs) and unstable features.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• The value ' ' cannot contain a comma. Deno separates values…
• Deno permission values cannot be null or empty.
• The inspect mode must be a defined DenoInspectMode value.
• The node_modules mode must be a defined…
• The permission kind must be a defined DenoPermissionKind…

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

Appendix: source

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

    /// <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> WithDenoUnstable(this IResourceBuilder<DenoAppResource> builder, params string[] features)
    {
        ArgumentNullException.ThrowIfNull(builder);
        var annotation = GetOrAddDenoAnnotation(builder);
        foreach (var feature in features ?? [])
        {
            if (string.IsNullOrEmpty(feature))
            {
                continue;
            }

            if (feature.StartsWith("--", StringComparison.Ordinal) &&
                !feature.StartsWith("--unstable-", StringComparison.Ordinal))
            {
                throw new ArgumentException("Qualified Deno unstable flags must start with \"--unstable-\".", nameof(features));
            }

            annotation.UnstableFlags.Add(feature.StartsWith("--unstable-", StringComparison.Ordinal) ? feature : $"--unstable-{feature}");
        }

        return builder;
    }

    // ---- Watch / inspect --------------------------------------------------------------------

    /// <summary>Enables <c>--watch</c> (or <c>--watch-hmr</c> when <paramref name="hmr"/> is <see langword="true"/>).</summary>
    /// <param name="builder">The Deno app resource builder.</param>
    /// <param name="hmr">Whether to emit <c>--watch-hmr</c> instead of <c>--watch</c>.</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> WithDenoWatch(this IResourceBuilder<DenoAppResource> builder, bool hmr = false)

View on GitHub (pinned to 25830f84bd)