github/copilot-sdk · error · ValueError

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

Error message

Invalid {value!r}. Expected 'inprocess', 'stdio', or unset.

What it means

When no explicit connection is supplied, the client reads the default connection kind from an environment variable (_DEFAULT_CONNECTION_ENV_VAR, e.g. COPILOT_CONNECTION). Only 'inprocess' or 'stdio' (case-insensitive) are accepted; anything else raises ValueError.

Solutions

  1. Set the env var to exactly 'inprocess' or 'stdio' (case-insensitive)
  2. Unset the env var to fall back to the default (stdio) connection
  3. Check shell profiles/CI files for typos in the variable's value

Example fix

// before
export COPILOT_CONNECTION=in-process
// after
export COPILOT_CONNECTION=inprocess
Defensive patterns

Strategy: validation

Validate before calling

v = os.environ.get("COPILOT_CONNECTION", "")
assert v.lower() in ("", "inprocess", "stdio"), f"bad COPILOT_CONNECTION={v!r}"

Type guard

def is_valid_connection_value(v: str | None) -> bool:
    return v is None or v.strip().lower() in ("inprocess", "stdio")

Try / catch

try:
    client = CopilotClient()
except ValueError as e:
    if "Expected 'inprocess', 'stdio'" in str(e):
        os.environ.pop("COPILOT_CONNECTION", None)
        client = CopilotClient()

Prevention

When it happens

Trigger: Setting the connection environment variable to a typo like 'in-proces', 'stdio ' with stray characters already stripped but wrong words like 'child-process', or leaving a stale value like 'tcp' in the environment.

Common situations: Typo in .env or CI config; copying an env var from another project; a variable set by an old script version before 'inprocess' was supported.

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

Appendix: source

Thrown at python/copilot/client.py:1472

_DEFAULT_CONNECTION_ENV_VAR = "COPILOT_SDK_DEFAULT_CONNECTION"


def _resolve_default_connection(env: Mapping[str, str]) -> RuntimeConnection:
    """Resolve the transport when the caller supplies no explicit connection.

    Honors the ``COPILOT_SDK_DEFAULT_CONNECTION`` override (``"inprocess"`` or
    ``"stdio"``); defaults to stdio. Matches the Node/.NET/Rust default-transport
    override so the CI matrix can run the whole suite under either transport.
    """
    value = env.get(_DEFAULT_CONNECTION_ENV_VAR)
    if value is None or value == "":
        return RuntimeConnection.for_stdio()
    normalized = value.strip().lower()
    if normalized == "inprocess":
        return RuntimeConnection.for_inprocess()
    if normalized == "stdio":
        return RuntimeConnection.for_stdio()
    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(

View on GitHub (pinned to cd8cf15dc3)