github/copilot-sdk · error · ArgumentException

Unsupported RuntimeConnection type

Error message

Unsupported RuntimeConnection type: <type name>

What it means

The constructor switches on the concrete RuntimeConnection type (in-process, TCP, URI) and its default branch rejects any unrecognized connection implementation with ArgumentException, naming the type. Only SDK-supported connection types are accepted.

Solutions

  1. Use one of the supported connections: InProcessRuntimeConnection, TcpRuntimeConnection, or UriRuntimeConnection/ForUri
  2. Remove the custom RuntimeConnection subclass or contribute support upstream
  3. Check the SDK version's supported connection types after an upgrade

Example fix

// before
options.Connection = new MyCustomConnection();
// after
options.Connection = new TcpRuntimeConnection();
Defensive patterns

Strategy: validation

Validate before calling

if (options.Connection is { } c && c is not InProcessRuntimeConnection && c is not TcpRuntimeConnection && c is not UriRuntimeConnection) throw new InvalidOperationException($"Unsupported connection type {c.GetType().Name}");

Try / catch

try { client = new CopilotClient(options); } catch (ArgumentException ex) when (ex.Message.Contains("Unsupported RuntimeConnection")) { options.Connection = new TcpRuntimeConnection(); client = new CopilotClient(options); }

Prevention

When it happens

Trigger: new CopilotClient(options) where options.Connection is a custom class deriving from RuntimeConnection (or an unsupported built-in) that the switch does not handle.

Common situations: Implementing a custom RuntimeConnection subclass expecting the SDK to honor it; upgrading the SDK where an older connection type was dropped; passing the wrong concrete type due to a factory bug.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/aa332a4a7ebf68c1. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Client.cs:185

                tcp.ConnectionToken ??= Guid.NewGuid().ToString();
                break;

            case UriRuntimeConnection uri:
                if (string.IsNullOrEmpty(uri.Url))
                {
                    throw new ArgumentException("UriRuntimeConnection.Url must be a non-empty string.", nameof(options));
                }
                if (!string.IsNullOrEmpty(_options.GitHubToken) || _options.UseLoggedInUser != null)
                {
                    throw new ArgumentException("GitHubToken and UseLoggedInUser cannot be combined with RuntimeConnection.ForUri (the existing runtime manages its own auth).", nameof(options));
                }
                var parsed = ParseRuntimeUrl(uri.Url);
                _optionsHost = parsed.Host.Trim('[', ']');
                _optionsPort = parsed.Port;
                break;

            default:
                throw new ArgumentException($"Unsupported RuntimeConnection type: {_connection.GetType().Name}", nameof(options));
        }

        ValidateEnvironmentOptions(_options, _connection);

        _logger = _options.Logger ?? NullLogger.Instance;
        _onListModels = _options.OnListModels;

        _clientGlobalApis = BuildClientGlobalApis();

        // Empty mode: validate at construction time that the app supplied a
        // per-session persistence location. The runtime is mode-agnostic, so
        // without this check it would silently fall back to ~/.copilot, which
        // defeats the point of empty mode for multi-tenant scenarios.
        if (_options.Mode == CopilotClientMode.Empty)
        {
            var hasPersistence =
                !string.IsNullOrEmpty(_options.BaseDirectory) ||
                _options.SessionFs is not null ||

View on GitHub (pinned to cd8cf15dc3)