microsoft/aspire · error · TerminalHostArgsException

{parse errors joined by '; '}

Error message

{parse errors joined by '; '}

What it means

TerminalHostArgs.Parse aggregates all command-line parse failures from the args model and throws a single TerminalHostArgsException whose message is the individual errors joined by '; '. It indicates one or more required or malformed arguments were supplied to the Terminal Host CLI.

Solutions

1. Read the '; '-joined message to see every failing argument and fix each one in the launch command
2. Ensure both producer and consumer UDS path options are passed with valid values
3. Check launchProfiles.json / script quoting so paths with spaces survive shell splitting

Example fix

// before
dotnet TerminalHost --producer-uds-path /tmp/p.sock
// after
dotnet TerminalHost --producer-uds-path /tmp/p.sock --consumer-uds-path /tmp/c.sock

if (args.Length == 0 || !args.Contains("--producer-uds-path") || !args.Contains("--consumer-uds-path"))
    throw new ArgumentException("Both --producer-uds-path and --consumer-uds-path are required.");

try { var hostArgs = TerminalHostArgs.Parse(args); }
catch (TerminalHostArgsException ex) { Console.Error.WriteLine(ex.Message); return 1; }

When it happens

Trigger: Running the Terminal Host with missing required options (e.g. missing --producer-uds-path or --consumer-uds-path) or values that fail option validation; System.CommandLine reports each failure and Parse joins them.

Common situations: Launching the terminal host from a script or debugger with a stale or truncated command line; quotes/paths with spaces breaking argument splitting; hand-edited launch profiles omitting one of the two UDS path options.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Could not parse Helm version from 'helm version --short'…
• Failed to parse template version from stdout.
• Integration closure metadata line
• Invalid value " " for "--dcp-dependency-check-timeout"…
• Already connected to AppHost backchannel.

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

Appendix: source

Thrown at src/Aspire.TerminalHost/TerminalHostArgs.cs:125

            shellOption,
        };
        // The terminal host argv comes from DCP only; treat unknown flags as a hard error
        // so we don't silently accept garbage and start with the wrong configuration.
        command.TreatUnmatchedTokensAsErrors = true;

        var parseResult = command.Parse(args);
        if (parseResult.Errors.Count > 0)
        {
            var message = new StringBuilder();
            foreach (var error in parseResult.Errors)
            {
                if (message.Length > 0)
                {
                    message.Append("; ");
                }
                message.Append(error.Message);
            }
            throw new TerminalHostArgsException(message.ToString());
        }

        return new TerminalHostArgs
        {
            ProducerUdsPath = parseResult.GetValue(producerOption)!,
            ConsumerUdsPath = parseResult.GetValue(consumerOption)!,
            ControlUdsPath = parseResult.GetValue(controlOption)!,
            Columns = parseResult.GetValue(columnsOption),
            Rows = parseResult.GetValue(rowsOption),
        };
    }

    private static Option<T> SingleValueOption<T>(
        string name,
        bool required,
        string description,
        T? defaultValue = default)
    {

View on GitHub (pinned to 25830f84bd)