{"record":{"id":"dcc4fc19d6fa2aad","repo":"github/copilot-sdk","slug":"invalid-copilotclient-default-connection-env-var","errorCode":null,"errorMessage":"Invalid ${CopilotClient.DEFAULT_CONNECTION_ENV_VAR} value '${value}'. Expected 'inprocess', 'stdio', or unset.","messagePattern":"Invalid (.+?) value '(.+?)'\\. Expected 'inprocess', 'stdio', or unset\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":562,"sourceCode":"     * {@link CopilotClientOptions.connection}. Accepts `\"inprocess\"` or `\"stdio\"`\n     * (case-insensitive); unset preserves the default stdio transport. Any other value\n     * is an error.\n     */\n    private static readonly DEFAULT_CONNECTION_ENV_VAR = \"COPILOT_SDK_DEFAULT_CONNECTION\";\n\n    /**\n     * Resolves the default {@link RuntimeConnection} for the no-connection case,\n     * honoring {@link CopilotClient.DEFAULT_CONNECTION_ENV_VAR}.\n     */\n    private static resolveDefaultConnection(): RuntimeConnection {\n        const value = process.env[CopilotClient.DEFAULT_CONNECTION_ENV_VAR];\n        if (!value || value.toLowerCase() === \"stdio\") {\n            return { kind: \"stdio\" };\n        }\n        if (value.toLowerCase() === \"inprocess\") {\n            return { kind: \"inprocess\" };\n        }\n        throw new Error(\n            `Invalid ${CopilotClient.DEFAULT_CONNECTION_ENV_VAR} value '${value}'. ` +\n                `Expected 'inprocess', 'stdio', or unset.`\n        );\n    }\n\n    /**\n     * Creates a new CopilotClient instance.\n     *\n     * @param options - Configuration options for the client\n     *\n     * @example\n     * ```typescript\n     * // Default: spawns the bundled runtime over stdio\n     * const client = new CopilotClient();\n     *\n     * // Connect to an existing runtime\n     * const client = new CopilotClient({\n     *   connection: RuntimeConnection.forUri(\"localhost:3000\"),","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L544-L580","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nawait client.create_session(model=\"gpt-4o\")\n// after\nawait client.create_session(\n    model=\"gpt-4o\",\n    create_session_fs_handler=lambda s: MySessionFsProvider(s),\n)","handlingStrategy":"validation","validationCode":"if getattr(client, \"_session_fs_config\", None) and create_session_fs_handler is None:\n    raise ValueError(\"create_session_fs_handler is required when session_fs is enabled\")","typeGuard":"def session_fs_ready(client, handler) -> bool:\n    return not getattr(client, \"_session_fs_config\", None) or callable(handler)","tryCatchPattern":"try:\n    session = await client.create_session(...)\nexcept ValueError as e:\n    if \"create_session_fs_handler is required\" in str(e):\n        session = await client.create_session(\n            ..., create_session_fs_handler=make_fs_handler)","preventionTips":["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."],"tags":["argument-validation","session-fs","configuration"],"backgroundTag":"missing-required-argument","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}