github/copilot-sdk · error · ValueError

env is not supported with…

Error message

env is not supported with RuntimeConnection.for_inprocess(): 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

The in-process transport loads the native runtime into the shared host process, which has a single environment block that cannot carry per-client values. Passing options.env while using RuntimeConnection.for_inprocess() is therefore rejected with ValueError so the misconfiguration fails loud instead of being silently ignored.

Solutions

Remove the env option and set the needed variables in the host process environment before creating the client
Switch to a child-process transport (RuntimeConnection.for_stdio()) if per-client env isolation is required

Example fix

// before
client = CopilotClient(connection=RuntimeConnection.for_inprocess(), env={"GITHUB_TOKEN": t})
// after
os.environ["GITHUB_TOKEN"] = t
client = CopilotClient(connection=RuntimeConnection.for_inprocess())

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(conn, InProcessRuntimeConnection) and opts.env is not None:
    raise ValueError("env is unsupported for in-process; use host process environment")

Type guard

def supports_client_env(conn) -> bool:
    return not isinstance(conn, InProcessRuntimeConnection)

Try / catch

try:
    client = CopilotClient(connection=conn, env=env)
except ValueError as e:
    if "env is not supported" in str(e):
        os.environ.update(env); env = None
        client = CopilotClient(connection=conn)

Prevention

Keep an options builder that drops per-process options for in-process transports
Document transport choice centrally in one factory function
Test client construction with each transport in CI

When it happens

Trigger: Creating CopilotClient with RuntimeConnection.for_inprocess() and a non-None env dict in _CopilotClientOptions.

Common situations: Migrating code from a stdio/child-process transport to in-process without removing env customization; trying to inject API keys per-client in embedded hosts.

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/8a61ba1cb7e867c6. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/client.py:1490

    raise ValueError(
        f"Invalid {_DEFAULT_CONNECTION_ENV_VAR}={value!r}. Expected 'inprocess', 'stdio', or unset."
    )


def _validate_environment_options(
    options: _CopilotClientOptions, connection: RuntimeConnection
) -> None:
    """Validate env/telemetry/working-directory options against the 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 and process-global working directory cannot carry per-client values,
    so options that lower to them are rejected there (fail loud, not silent).
    """
    if isinstance(connection, InProcessRuntimeConnection):
        if options.env is not None:
            raise ValueError(
                "env is not supported with RuntimeConnection.for_inprocess(): 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."
            )
        if options.telemetry is not None:
            raise ValueError(
                "telemetry is not supported with RuntimeConnection.for_inprocess(): "
                "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."
            )
        if options.working_directory is not None:
            raise ValueError(
                "working_directory is not supported with RuntimeConnection.for_inprocess(): "
                "the native runtime shares the host process working directory, so a "
                "per-client working directory cannot be honored in-process. Use a "

View on GitHub (pinned to cd8cf15dc3)