github/copilot-sdk · error · ValueError

create_session_fs_handler is required in session config…

Error message

create_session_fs_handler is required in session config when session_fs is enabled in client options.

What it means

Validation inside create_session: the client was constructed with session_fs enabled (a session_fs config is present in client options), which requires a per-session filesystem handler factory, but create_session was called without create_session_fs_handler. The session cannot mount its virtual filesystem without it, so construction aborts.

Solutions

1. Pass a create_session_fs_handler callable to create_session
2. Build the handler from the session_fs config supplied in the client options
3. Disable session_fs in the client options if the session does not need a virtual filesystem

When it happens

Trigger: Thrown at python/copilot/client.py:2877 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at python/copilot/client.py:2877

            """
            setup_start = time.perf_counter()
            s = CopilotSession(
                sid,
                self._client,
                workspace_path=None,
                managed_settings_enabled=enable_managed_settings is True
                or managed_settings is not None,
                on_disconnect=(
                    None
                    if github_token_provider_registration_id is None
                    else lambda: self._unregister_github_token_provider(
                        github_token_provider_registration_id
                    )
                ),
            )
            if self._session_fs_config:
                if create_session_fs_handler is None:
                    raise ValueError(
                        "create_session_fs_handler is required in session config when "
                        "session_fs is enabled in client options."
                    )
                fs_provider: SessionFsProvider = create_session_fs_handler(s)
                caps = self._session_fs_config.get("capabilities")
                if caps and caps.get("sqlite"):
                    from .session_fs_provider import SessionFsSqliteProvider

                    if not isinstance(fs_provider, SessionFsSqliteProvider):
                        raise ValueError(
                            "SessionFs capabilities declare SQLite support but the provider "
                            "does not implement SessionFsSqliteProvider"
                        )
                s._client_session_apis.session_fs = create_session_fs_adapter(fs_provider)
            s._register_tools(tools)
            s._register_commands(commands)
            s._register_permission_handler(on_permission_request)
            s._register_mcp_auth_handler(on_mcp_auth_request)

View on GitHub (pinned to cd8cf15dc3)