microsoft/aspire · error · ArgumentException

Options must be omitted, a string array, or a…

Error message

Options must be omitted, a string array, or a CreateBuilderOptions instance.

What it means

DistributedApplication.CreateBuilderForPolyglot accepts an argument that may be omitted, a string[] of args, or a CreateBuilderOptions instance. Any other object type (common with polyglot callers passing dictionaries, strings, or named-arg objects) is rejected with ArgumentException.

Solutions

1. Pass the args as a string[], e.g. ["--port", "7000"], splitting any single command-line string yourself.
2. Construct CreateBuilderOptions and set its properties for structured configuration.
3. Omit the parameter entirely to use defaults.
4. Inspect the actual runtime type of the value you pass and convert it before the call.

Example fix

// before
var app = DistributedApplication.CreateBuilderForPolyglot("--port 7000"); // string -> throws
// after
var app = DistributedApplication.CreateBuilderForPolyglot(new[] { "--port", "7000" });

bool ok = argsOrOptions is null or string[] or CreateBuilderOptions;
if (!ok) throw new ArgumentException("Pass null, string[], or CreateBuilderOptions.", nameof(argsOrOptions));

static bool IsValidCreateBuilderInput(object? o) => o is null or string[] or CreateBuilderOptions;

try { var app = DistributedApplication.CreateBuilderForPolyglot(input); }
catch (ArgumentException ex) when (ex.ParamName == nameof(input)) { /* normalize input to string[] or CreateBuilderOptions */ }

When it happens

Trigger: Calling CreateBuilderForPolyglot with a single string, a List<string>, a dictionary of options, or any object other than null/string[]/CreateBuilderOptions.

Common situations: Polyglot notebooks (F#, Python via wire protocols) or scripts passing a single command-line string like "--port 7000" instead of splitting into an array, or passing a JSON-parsed options object of the wrong shape.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Application Insights must be omitted, a location string, a…
• Deployment slot must be a string or a parameter resource…
• Launch profile must be a string or ProjectResourceOptions.
• -32000
• -32603

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

Appendix: source

Thrown at src/Aspire.Hosting/DistributedApplication.cs:281

            realOptions.AppHostFilePath = options.AppHostFilePath;
        }

        return new DistributedApplicationBuilder(realOptions);
    }

    /// <summary>
    /// Creates a new distributed application builder
    /// </summary>
    [AspireExport("createBuilder")]
    internal static IDistributedApplicationBuilder CreateBuilderForPolyglot(
        [AspireUnion(typeof(string[]), typeof(CreateBuilderOptions))] object? argsOrOptions = null)
    {
        return argsOrOptions switch
        {
            null => CreateBuilder(),
            string[] args => CreateBuilder(args),
            CreateBuilderOptions options => CreateBuilder(options),
            _ => throw new ArgumentException("Options must be omitted, a string array, or a CreateBuilderOptions instance.", nameof(argsOrOptions))
        };
    }

    private static void WaitForDebugger()
    {
        if (Environment.GetEnvironmentVariable(KnownConfigNames.WaitForDebugger) == "true")
        {
            var startedWaiting = DateTimeOffset.UtcNow;
            var timeout = TimeSpan.FromSeconds(30);

            if (Environment.GetEnvironmentVariable(KnownConfigNames.WaitForDebuggerTimeout) is string timeoutString && int.TryParse(timeoutString, out var timeoutSeconds))
            {
                timeout = TimeSpan.FromSeconds(timeoutSeconds);
            }

            Console.WriteLine($"AppHost PID: {Environment.ProcessId}");

            while (Debugger.IsAttached == false)

View on GitHub (pinned to 25830f84bd)