{"record":{"id":"5a7d878c89df95f0","repo":"github/copilot-sdk","slug":"connectiontoken-must-be-a-non-empty-string-or-null","errorCode":null,"errorMessage":"ConnectionToken must be a non-empty string or null.","messagePattern":"ConnectionToken must be a non-empty string or null\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Client.cs","lineNumber":163,"sourceCode":"        {\n            throw new ArgumentException(\n                $\"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.BuiltinPluginDirectories)} \" +\n                $\"must contain only absolute paths: {path}\",\n                nameof(options));\n        }\n\n        switch (_connection)\n        {\n            case StdioRuntimeConnection:\n                break;\n\n            case InProcessRuntimeConnection:\n                break;\n\n            case TcpRuntimeConnection tcp:\n                if (tcp.ConnectionToken is { Length: 0 })\n                {\n                    throw new ArgumentException(\"ConnectionToken must be a non-empty string or null.\", nameof(options));\n                }\n                // Auto-generate a connection token when the SDK spawns the runtime over TCP\n                // so the loopback listener is safe by default.\n                tcp.ConnectionToken ??= Guid.NewGuid().ToString();\n                break;\n\n            case UriRuntimeConnection uri:\n                if (string.IsNullOrEmpty(uri.Url))\n                {\n                    throw new ArgumentException(\"UriRuntimeConnection.Url must be a non-empty string.\", nameof(options));\n                }\n                if (!string.IsNullOrEmpty(_options.GitHubToken) || _options.UseLoggedInUser != null)\n                {\n                    throw new ArgumentException(\"GitHubToken and UseLoggedInUser cannot be combined with RuntimeConnection.ForUri (the existing runtime manages its own auth).\", nameof(options));\n                }\n                var parsed = ParseRuntimeUrl(uri.Url);\n                _optionsHost = parsed.Host.Trim('[', ']');\n                _optionsPort = parsed.Port;","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/Client.cs#L145-L181","documentation":"For a TcpRuntimeConnection, the constructor requires ConnectionToken to be either null or a non-empty string; an empty string is rejected with ArgumentException. When null, the SDK auto-generates a GUID token so the loopback listener is safe by default.","triggerScenarios":"new CopilotClient(options) where options.Connection is a TcpRuntimeConnection whose ConnectionToken is set to string.Empty (Length == 0).","commonSituations":"Reading the token from an env var or config that is defined but empty (COPILOT_TOKEN=\"\"); initializing string fields to \"\" as a placeholder; deserializing connection settings where the token came back as an empty string.","solutions":["Set ConnectionToken to null to let the SDK auto-generate one","Provide a real non-empty token string","Guard config loading: treat empty-string tokens as null before constructing options"],"exampleFix":"// before\ntcp.ConnectionToken = Environment.GetEnvironmentVariable(\"COPILOT_TOKEN\") ?? \"\";\n// after\ntcp.ConnectionToken = string.IsNullOrEmpty(Environment.GetEnvironmentVariable(\"COPILOT_TOKEN\")) ? null : Environment.GetEnvironmentVariable(\"COPILOT_TOKEN\");","handlingStrategy":"validation","validationCode":"tcp.ConnectionToken = string.IsNullOrEmpty(rawToken) ? null : rawToken;","typeGuard":null,"tryCatchPattern":"try { client = new CopilotClient(options); } catch (ArgumentException ex) when (ex.Message.Contains(\"ConnectionToken\")) { ((TcpRuntimeConnection)options.Connection).ConnectionToken = null; client = new CopilotClient(options); }","preventionTips":["Normalize empty config strings to null at load time","Let the SDK auto-generate the token unless explicitly configured","Log config values' presence, not contents, during startup validation"],"tags":["dotnet","tcp","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}