What causes "Invalid value ' '. Expected 'inprocess', 'stdio', or unset." in github/copilot-sdk?

Set the environment variable to exactly 'inprocess' or 'stdio' (case-insensitive).

github/copilot-sdk · error · ArgumentException

Invalid value ' '. Expected 'inprocess', 'stdio', or unset.

Error message

Invalid <env var name> value '<value>'. Expected 'inprocess', 'stdio', or unset.

What it means

ResolveDefaultConnection throws this ArgumentException when the environment variable named by DefaultConnectionEnvVar is set to a value other than 'inprocess', 'stdio', or unset/empty. The variable selects the default runtime connection; unknown values are rejected with this message listing the valid options.

Solutions

Set the environment variable to exactly 'inprocess' or 'stdio' (case-insensitive).
Unset or clear the variable to use the library default.
Pass an explicit RuntimeConnection (ForStdio/ForInProcess) in code so the env var is not consulted.

Example fix

// before
set COPILOT_SDK_CONNECTION=in_process   // invalid
// after
set COPILOT_SDK_CONNECTION=inprocess   // or 'stdio', or unset

Defensive patterns

Strategy: validation

Validate before calling

var v = Environment.GetEnvironmentVariable(DefaultConnectionEnvVar);
if (v is not (null or "") && !string.Equals(v, "inprocess", StringComparison.OrdinalIgnoreCase) && !string.Equals(v, "stdio", StringComparison.OrdinalIgnoreCase))
    throw new ArgumentException($"{DefaultConnectionEnvVar} must be 'inprocess' or 'stdio'.");

Type guard

static bool IsValidConnectionEnvValue(string? v) => string.IsNullOrWhiteSpace(v) || v.Equals("inprocess", StringComparison.OrdinalIgnoreCase) || v.Equals("stdio", StringComparison.OrdinalIgnoreCase);

Try / catch

try { client = new CopilotClient(options); }
catch (ArgumentException ex) when (ex.Message.Contains(DefaultConnectionEnvVar)) { client = new CopilotClient(options, RuntimeConnection.ForStdio()); }

Prevention

Validate env config at deployment/CI time
Pass an explicit RuntimeConnection in code to bypass the env var
Document allowed values ('inprocess', 'stdio') wherever the variable is set

When it happens

Trigger: Creating a CopilotClient without an explicit RuntimeConnection while the DefaultConnectionEnvVar environment variable contains a typo or unsupported value, e.g. 'IN-PROCESS', 'ipc', 'ffi', or 'true'.

Common situations: Typos in CI/CD or launch profiles; users guessing at values like 'in_process' or 'childprocess'; stale variables left from experiments with older SDK versions.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

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

Appendix: source

Thrown at dotnet/src/Client.cs:304

    /// Resolves the default <see cref="RuntimeConnection"/> for the no-Connection case,
    /// honoring <see cref="DefaultConnectionEnvVar"/>.
    /// </summary>
    private static RuntimeConnection ResolveDefaultConnection(CopilotClientOptions options)
    {
        var value = options.Environment is not null
            && options.Environment.TryGetValue(DefaultConnectionEnvVar, out var fromOptions)
                ? fromOptions
                : Environment.GetEnvironmentVariable(DefaultConnectionEnvVar);

        if (string.IsNullOrEmpty(value) || string.Equals(value, "stdio", StringComparison.OrdinalIgnoreCase))
        {
            return RuntimeConnection.ForStdio();
        }
        if (string.Equals(value, "inprocess", StringComparison.OrdinalIgnoreCase))
        {
            return RuntimeConnection.ForInProcess();
        }
        throw new ArgumentException(
            $"Invalid {DefaultConnectionEnvVar} value '{value}'. Expected 'inprocess', 'stdio', or unset.");
    }

    /// <summary>
    /// Parses a runtime URL into a URI with host and port.
    /// </summary>
    /// <param name="url">The URL to parse. Supports formats: "port", "host:port", "[ipv6]:port", "http://host:port".</param>
    private static Uri ParseRuntimeUrl(string url)
    {
        // If it's just a port number, treat as localhost
        if (int.TryParse(url, out var port))
        {
            return new Uri($"http://localhost:{port}");
        }

        // Add scheme if missing
        if (!url.StartsWith("http://", StringComparison.OrdinalIgnoreCase) &&
            !url.StartsWith("https://", StringComparison.OrdinalIgnoreCase))

View on GitHub (pinned to cd8cf15dc3)