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

Error message

Invalid ${CopilotClient.DEFAULT_CONNECTION_ENV_VAR} value '${value}'. Expected 'inprocess', 'stdio', or unset.

What it means

When session_fs is enabled in the client options (self._session_fs_config is set), CopilotClient._initialize_session() requires a create_session_fs_handler argument. This handler is the factory that builds the SessionFsProvider for the session; without it the library cannot implement the session-filesystem capability and raises this ValueError.

Solutions

Pass a create_session_fs_handler callable that accepts the session and returns a SessionFsProvider.
If session filesystem support is not needed, remove session_fs from the client options instead.
Wrap create_session in a helper that always supplies the handler when session_fs is configured.

Example fix

// before
await client.create_session(model="gpt-4o")
// after
await client.create_session(
    model="gpt-4o",
    create_session_fs_handler=lambda s: MySessionFsProvider(s),
)

Defensive patterns

Strategy: validation

Validate before calling

if getattr(client, "_session_fs_config", None) and create_session_fs_handler is None:
    raise ValueError("create_session_fs_handler is required when session_fs is enabled")

Type guard

def session_fs_ready(client, handler) -> bool:
    return not getattr(client, "_session_fs_config", None) or callable(handler)

Try / catch

try:
    session = await client.create_session(...)
except ValueError as e:
    if "create_session_fs_handler is required" in str(e):
        session = await client.create_session(
            ..., create_session_fs_handler=make_fs_handler)

Prevention

If you enable session_fs in client options, always supply the per-session handler.
Keep client-options construction and session-call sites in the same factory function.
Add an integration test covering a session_fs-enabled client creating sessions.

When it happens

Trigger: Constructing CopilotClient with a session_fs config (e.g. {"capabilities": {...}}) in the client options, then calling create_session()/_initialize_session() without passing create_session_fs_handler.

Common situations: Enabling session_fs in shared client options but forgetting the per-session handler; adding session_fs support to an existing call site that predates the option; a wrapper that forwards client options but not the handler argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/src/client.ts:562

     * {@link CopilotClientOptions.connection}. Accepts `"inprocess"` or `"stdio"`
     * (case-insensitive); unset preserves the default stdio transport. Any other value
     * is an error.
     */
    private static readonly DEFAULT_CONNECTION_ENV_VAR = "COPILOT_SDK_DEFAULT_CONNECTION";

    /**
     * Resolves the default {@link RuntimeConnection} for the no-connection case,
     * honoring {@link CopilotClient.DEFAULT_CONNECTION_ENV_VAR}.
     */
    private static resolveDefaultConnection(): RuntimeConnection {
        const value = process.env[CopilotClient.DEFAULT_CONNECTION_ENV_VAR];
        if (!value || value.toLowerCase() === "stdio") {
            return { kind: "stdio" };
        }
        if (value.toLowerCase() === "inprocess") {
            return { kind: "inprocess" };
        }
        throw new Error(
            `Invalid ${CopilotClient.DEFAULT_CONNECTION_ENV_VAR} value '${value}'. ` +
                `Expected 'inprocess', 'stdio', or unset.`
        );
    }

    /**
     * Creates a new CopilotClient instance.
     *
     * @param options - Configuration options for the client
     *
     * @example
     * ```typescript
     * // Default: spawns the bundled runtime over stdio
     * const client = new CopilotClient();
     *
     * // Connect to an existing runtime
     * const client = new CopilotClient({
     *   connection: RuntimeConnection.forUri("localhost:3000"),

View on GitHub (pinned to cd8cf15dc3)