github/copilot-sdk · error · ValueError

Set environment variables via either the client-level env…

Error message

Set environment variables via either the client-level env argument or ChildProcessRuntimeConnection.env, not both. Prefer the connection-level env for child-process transports.

What it means

Environment variables can be provided either via the client-level env option or via ChildProcessRuntimeConnection.env; supplying both is ambiguous and rejected with ValueError. The library asks callers to prefer the connection-level env for child-process transports.

Solutions

Remove the client-level env option and keep env on ChildProcessRuntimeConnection.env (preferred)
Or remove connection.env and keep the client-level env argument

Example fix

// before
conn = RuntimeConnection.for_stdio(env={"FOO": "1"})
client = CopilotClient(connection=conn, env={"BAR": "2"})
// after
conn = RuntimeConnection.for_stdio(env={"FOO": "1", "BAR": "2"})
client = CopilotClient(connection=conn)

Defensive patterns

Strategy: validation

Validate before calling

if isinstance(conn, ChildProcessRuntimeConnection) and conn.env is not None and opts.env is not None:
    raise ValueError("set env on connection or options, not both")

Type guard

def env_config_is_unambiguous(conn, opts) -> bool:
    return not (isinstance(conn, ChildProcessRuntimeConnection) and conn.env is not None and opts.env is not None)

Try / catch

try:
    client = CopilotClient(connection=conn, env=env)
except ValueError as e:
    if "not both" in str(e):
        client = CopilotClient(connection=conn)  # connection.env wins

Prevention

Adopt one convention: always set env on the connection object for child-process transports
Wrap client construction in a helper that merges env into the connection
Add a unit test asserting env is only ever set in one place

When it happens

Trigger: Creating CopilotClient with a ChildProcessRuntimeConnection whose env is set AND passing a non-None env in _CopilotClientOptions.

Common situations: A wrapper that always sets client-level env while the connection object was built with env; refactoring code that moved env from options to the connection but left the old value in place.

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/01462d171a008cce. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/client.py:1519

                "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 "
                "child-process "
                "transport, or set the process working directory before creating the client."
            )
        return

    if (
        isinstance(connection, ChildProcessRuntimeConnection)
        and connection.env is not None
        and options.env is not None
    ):
        raise ValueError(
            "Set environment variables via either the client-level env argument or "
            "ChildProcessRuntimeConnection.env, not both. Prefer the connection-level "
            "env for child-process transports."
        )


class CopilotClient:
    """
    Main client for interacting with the Copilot CLI.

    The CopilotClient manages the connection to the Copilot CLI server and provides
    methods to create and manage conversation sessions. It can either spawn a CLI
    server process or connect to an existing server.

    The client supports both stdio (default) and TCP transport modes for
    communication with the CLI server.

    Example:

View on GitHub (pinned to cd8cf15dc3)