github/copilot-sdk · error · ArgumentException

UriRuntimeConnection.Url must be a non-empty string.

Error message

UriRuntimeConnection.Url must be a non-empty string.

What it means

Argument-validation guard in CopilotClient's connection-options handling (same ArgumentException pattern as the sibling TcpRuntimeConnection check): a UriRuntimeConnection was supplied whose Url is null, empty, or not a string. The faulting input is the RuntimeConnection option; supply a valid non-empty absolute URL before constructing the client.

Solutions

  1. Set UriRuntimeConnection.Url to a valid runtime URL (e.g. http://127.0.0.1:port)
  2. Validate the config/env value before building options
  3. Fall back to a default connection (omit Connection) when no URL is configured

Example fix

// before
options.Connection = new UriRuntimeConnection { Url = cfg["RuntimeUrl"] }; // empty
// after
var url = cfg["RuntimeUrl"];
if (string.IsNullOrEmpty(url)) throw new InvalidOperationException("RuntimeUrl must be configured");
options.Connection = new UriRuntimeConnection { Url = url };
Defensive patterns

Strategy: validation

Validate before calling

if (options.Connection is UriRuntimeConnection u && string.IsNullOrEmpty(u.Url)) throw new InvalidOperationException("Configure RuntimeConnection.ForUri with a non-empty URL");

Try / catch

try { client = new CopilotClient(options); } catch (ArgumentException ex) when (ex.Message.Contains("UriRuntimeConnection.Url")) { log.LogError(ex, "Runtime URL not configured"); }

Prevention

When it happens

Trigger: new CopilotClient(options) with options.Connection = new UriRuntimeConnection { Url = null } or Url = ""; RuntimeConnection.ForUri built from a null/empty variable.

Common situations: Runtime URL read from an unset or empty environment variable/config key; constructing the options object without assigning Url; template strings left unsubstituted.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at dotnet/src/Client.cs:173

                break;

            case InProcessRuntimeConnection:
                break;

            case TcpRuntimeConnection tcp:
                if (tcp.ConnectionToken is { Length: 0 })
                {
                    throw new ArgumentException("ConnectionToken must be a non-empty string or null.", nameof(options));
                }
                // Auto-generate a connection token when the SDK spawns the runtime over TCP
                // so the loopback listener is safe by default.
                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;

View on GitHub (pinned to cd8cf15dc3)