{"record":{"id":"36a8e7af32608098","repo":"microsoft/aspire","slug":"options-must-be-omitted-a-string-array-or-a","errorCode":null,"errorMessage":"Options must be omitted, a string array, or a CreateBuilderOptions instance.","messagePattern":"Options must be omitted, a string array, or a CreateBuilderOptions instance\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/DistributedApplication.cs","lineNumber":281,"sourceCode":"            realOptions.AppHostFilePath = options.AppHostFilePath;\n        }\n\n        return new DistributedApplicationBuilder(realOptions);\n    }\n\n    /// <summary>\n    /// Creates a new distributed application builder\n    /// </summary>\n    [AspireExport(\"createBuilder\")]\n    internal static IDistributedApplicationBuilder CreateBuilderForPolyglot(\n        [AspireUnion(typeof(string[]), typeof(CreateBuilderOptions))] object? argsOrOptions = null)\n    {\n        return argsOrOptions switch\n        {\n            null => CreateBuilder(),\n            string[] args => CreateBuilder(args),\n            CreateBuilderOptions options => CreateBuilder(options),\n            _ => throw new ArgumentException(\"Options must be omitted, a string array, or a CreateBuilderOptions instance.\", nameof(argsOrOptions))\n        };\n    }\n\n    private static void WaitForDebugger()\n    {\n        if (Environment.GetEnvironmentVariable(KnownConfigNames.WaitForDebugger) == \"true\")\n        {\n            var startedWaiting = DateTimeOffset.UtcNow;\n            var timeout = TimeSpan.FromSeconds(30);\n\n            if (Environment.GetEnvironmentVariable(KnownConfigNames.WaitForDebuggerTimeout) is string timeoutString && int.TryParse(timeoutString, out var timeoutSeconds))\n            {\n                timeout = TimeSpan.FromSeconds(timeoutSeconds);\n            }\n\n            Console.WriteLine($\"AppHost PID: {Environment.ProcessId}\");\n\n            while (Debugger.IsAttached == false)","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/DistributedApplication.cs#L263-L299","documentation":"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.","triggerScenarios":"Calling CreateBuilderForPolyglot with a single string, a List<string>, a dictionary of options, or any object other than null/string[]/CreateBuilderOptions.","commonSituations":"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.","solutions":["Pass the args as a string[], e.g. [\"--port\", \"7000\"], splitting any single command-line string yourself.","Construct CreateBuilderOptions and set its properties for structured configuration.","Omit the parameter entirely to use defaults.","Inspect the actual runtime type of the value you pass and convert it before the call."],"exampleFix":"// before\nvar app = DistributedApplication.CreateBuilderForPolyglot(\"--port 7000\"); // string -> throws\n// after\nvar app = DistributedApplication.CreateBuilderForPolyglot(new[] { \"--port\", \"7000\" });","handlingStrategy":"type-guard","validationCode":"bool ok = argsOrOptions is null or string[] or CreateBuilderOptions;\nif (!ok) throw new ArgumentException(\"Pass null, string[], or CreateBuilderOptions.\", nameof(argsOrOptions));","typeGuard":"static bool IsValidCreateBuilderInput(object? o) => o is null or string[] or CreateBuilderOptions;","tryCatchPattern":"try { var app = DistributedApplication.CreateBuilderForPolyglot(input); }\ncatch (ArgumentException ex) when (ex.ParamName == nameof(input)) { /* normalize input to string[] or CreateBuilderOptions */ }","preventionTips":["Split single command-line strings into string[] before calling","Use CreateBuilderOptions for structured inputs","Document expected input types for polyglot callers"],"tags":["polyglot","argument-type","apphost"],"backgroundTag":"type-mismatch","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}