github/copilot-sdk · error · ArgumentException

CopilotClientOptions.Environment is not supported with…

Error message

CopilotClientOptions.Environment is not supported with RuntimeConnection.ForInProcess(): the in-process transport loads the native runtime into the shared host process, whose single environment block cannot carry per-client values. Set the variables on the host process environment instead.

What it means

CopilotClient throws this ArgumentException when CopilotClientOptions.Environment is set while using RuntimeConnection.ForInProcess(). The in-process transport loads the native runtime into the shared host process, which has a single environment block, so per-client environment variables cannot be applied. The library fails fast at construction rather than silently ignoring the values.

Solutions

  1. Remove Environment from CopilotClientOptions when using ForInProcess().
  2. Set the needed variables on the host process environment before startup (e.g. launchSettings, Dockerfile, shell export).
  3. Switch to RuntimeConnection.ForStdio() (ChildProcessRuntimeConnection) if per-client environment isolation is required.

Example fix

// before
var options = new CopilotClientOptions { Environment = new Dictionary<string,string> { ["GITHUB_TOKEN"] = token } };
var client = new CopilotClient(options, RuntimeConnection.ForInProcess());
// after
var options = new CopilotClientOptions(); // no Environment
Environment.SetEnvironmentVariable("GITHUB_TOKEN", token); // host process env
var client = new CopilotClient(options, RuntimeConnection.ForInProcess());
Defensive patterns

Strategy: validation

Validate before calling

if (connection is InProcessRuntimeConnection && options.Environment is not null)
    throw new InvalidOperationException("Set env vars on the host process when using ForInProcess().");

Type guard

static bool CanUseOptionsEnvironment(RuntimeConnection c) => c is not InProcessRuntimeConnection;

Try / catch

try { client = new CopilotClient(options, connection); }
catch (ArgumentException ex) when (ex.Message.Contains("Environment")) { /* fall back to stdio or env-free options */ }

Prevention

When it happens

Trigger: new CopilotClient(options, RuntimeConnection.ForInProcess()) where options.Environment is a non-null dictionary of environment variables. Validation happens in ValidateEnvironmentOptions during CopilotClient construction.

Common situations: Sharing a CopilotClientOptions object between child-process and in-process connections; migrating code from ForStdio() to ForInProcess() without removing Environment; trying to inject API keys or proxy settings per client in-process.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at dotnet/src/Client.cs:232

            }
        }
    }

    /// <summary>
    /// Validates environment-variable options against the resolved transport.
    /// Per-client environment is only representable for child-process transports
    /// (each client owns its own OS process). The in-process (FFI) transport
    /// loads the native runtime into the shared host process, whose single
    /// environment block cannot carry per-client values, so environment and
    /// telemetry options that lower to environment variables are rejected there.
    /// </summary>
    private static void ValidateEnvironmentOptions(CopilotClientOptions options, RuntimeConnection connection)
    {
        if (connection is InProcessRuntimeConnection)
        {
            if (options.Environment is not null)
            {
                throw new ArgumentException(
                    $"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.Environment)} is not supported with " +
                    $"{nameof(RuntimeConnection)}.{nameof(RuntimeConnection.ForInProcess)}(): the in-process transport " +
                    "loads the native runtime into the shared host process, whose single environment block cannot carry " +
                    "per-client values. Set the variables on the host process environment instead.",
                    nameof(options));
            }

            if (options.Telemetry is not null)
            {
                throw new ArgumentException(
                    $"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.Telemetry)} is not supported with " +
                    $"{nameof(RuntimeConnection)}.{nameof(RuntimeConnection.ForInProcess)}(): telemetry configuration is " +
                    "lowered to environment variables read by native runtime code running in the shared host process, so " +
                    "per-client telemetry cannot be honored in-process. Configure telemetry via the host process " +
                    "environment, or use a child-process transport.",
                    nameof(options));
            }

View on GitHub (pinned to cd8cf15dc3)