microsoft/aspire · error · NonInteractiveException

The option must be specified when running in…

Error message

The {0} option must be specified when running in non-interactive mode.

What it means

ThrowNonInteractiveError is the shared failure path for prompts in non-interactive mode: it first displays a localized error stating that the given option (symbol display name) must be specified, then throws NonInteractiveException carrying that option name. BaseCommand catches NonInteractiveException and converts it into the command's exit result.

Solutions

Specify the named option on the command line, exactly as shown in the error message.
Add a non-interactive default value binding for the prompt so the throw is not reached.
Catch NonInteractiveException at the command boundary (as BaseCommand does) to render a clean exit message.
Test commands with --non-interactive to find prompts lacking option bindings before shipping.

Example fix

// before
// error: The --environment option must be specified when running in non-interactive mode.
aspire deploy --non-interactive
// after
aspire deploy --non-interactive --environment production

Defensive patterns

Strategy: try-catch

Validate before calling

if (!hostEnvironment.SupportsInteractiveOutput && optionValue is null)
{
    interaction.DisplayError($"The {optionName} option must be specified when running in non-interactive mode.");
    return ExitCodeConstants.InvalidCommandUsage;
}

Try / catch

try { await command.ExecuteAsync(context); }
catch (NonInteractiveException ex)
{
    interaction.DisplayError($"The {ex.OptionName} option must be specified when running in non-interactive mode.");
    return ExitCodeConstants.InvalidCommandUsage;
}

Prevention

Mirror every interactive prompt with a command-line option.
Catch NonInteractiveException in BaseCommand-style boundaries for clean exits.
Include the option name in the error so users know what to pass.
Test each command with --non-interactive and no options.

When it happens

Trigger: Any ConsoleInteractionService prompt method invoked without interactive input while the prompt symbol has no non-interactive default; the symbol display name names the option the user should have passed.

Common situations: CI runs missing a required flag that mirrors an interactive prompt; new prompts added without a non-interactive counterpart option; users piping commands expecting prompts to auto-resolve.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Interaction/ConsoleInteractionService.cs:813

            if (match is null)
            {
                return null; // Signal that matching failed
            }
            // MatchChoice returns the instance from the choices list via FirstOrDefault,
            // so reference equality is correct here for deduplication.
            if (!matched.Contains(match))
            {
                matched.Add(match);
            }
        }
        return matched;
    }

    [DoesNotReturn]
    private void ThrowNonInteractiveError(string symbolDisplayName)
    {
        DisplayError(string.Format(CultureInfo.CurrentCulture, InteractionServiceStrings.NonInteractiveOptionRequired, symbolDisplayName));
        throw new NonInteractiveException(symbolDisplayName);
    }

    internal void ValidateResolvedStringValue(string value, bool required, Func<string, ValidationResult>? validator, string symbolDisplayName)
    {
        if (required && string.IsNullOrEmpty(value))
        {
            ThrowNonInteractiveError(symbolDisplayName);
        }

        if (validator is not null)
        {
            var result = validator(value);
            if (!result.Successful)
            {
                DisplayError(result.Message ?? string.Format(CultureInfo.CurrentCulture, InteractionServiceStrings.NonInteractiveInvalidValue, value, symbolDisplayName));
                throw new NonInteractiveException(symbolDisplayName);
            }
        }

View on GitHub (pinned to 25830f84bd)