github/copilot-sdk · error · ValueError

unknown session

Error message

unknown session {session_id}

What it means

ValueError raised by _get_client_session_handlers when no session is registered under the given session_id in self._sessions. The library looked up the session map and found nothing for that identifier.

Solutions

1. Verify the session was created (start_session/create session call) before use and keep the returned id
2. Check for events arriving after session disposal; ignore or re-create the session as appropriate
3. Ensure the same CopilotClient instance that created the session handles its callbacks
4. Log the sessionId and the set of known session ids to spot stale/mismatched identifiers

with client._sessions_lock:
    if session_id not in client._sessions:
        log.warning("stale session callback %s ignored", session_id)
        return None

def session_exists(client, session_id: str) -> bool:
    with client._sessions_lock:
        return session_id in client._sessions

try:
    handlers = client._get_client_session_handlers(session_id)
except ValueError as e:
    if str(e).startswith("unknown session"):
        recreate_or_ignore_session(session_id)
    else:
        raise

When it happens

Trigger: A callback/dispatch referencing a sessionId that was never created, was already deleted, or whose session object was removed; a stale or malformed session id passed to session-handler lookup.

Common situations: Events arriving after session disposal; client reconnecting with an old session id; resuming a session in a new process where the in-memory map is empty; a typo or parsing bug producing a wrong sessionId string.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• No session found for sessionId
• session.create returned sessionId
• Session not found
• Session ' ' is already tracked by this client.
• Cannot connect: no process for stdio and no host:port for…

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

Appendix: source

Thrown at python/copilot/client.py:4925

                registration = self._github_token_providers.get(registration_id)
                if registration is not None:
                    registration.session_id = session_id
                    registration.committed = True

    def _get_session(self, session_id: str) -> CopilotSession | None:
        with self._sessions_lock:
            return self._sessions.get(session_id)

    async def _set_llm_inference_provider(self) -> None:
        if self._request_handler is None or self._rpc is None:
            return
        await self._rpc.llm_inference.set_provider()

    def _get_client_session_handlers(self, session_id: str) -> ClientSessionApiHandlers:
        with self._sessions_lock:
            session = self._sessions.get(session_id)
        if session is None:
            raise ValueError(f"unknown session {session_id}")
        return session._client_session_apis

    async def _handle_user_input_request(self, params: dict) -> dict:
        """
        Handle a user input request from the CLI server.

        Args:
            params: The user input request parameters from the server.

        Returns:
            A dict containing the user's response.

        Raises:
            ValueError: If the request payload is invalid.
        """
        session_id = params.get("sessionId")
        question = params.get("question")

View on GitHub (pinned to cd8cf15dc3)