agentscope-ai/agentscope · error · KeyError

Session {session_id!r} not found.

Error message

Session {session_id!r} not found.

What it means

Raised by SQLStorage.update_session_state when the session row identified by session_id does not exist in the database. The method performs a read-modify-write on the session payload and cannot proceed on a missing row.

Source

Thrown at src/agentscope/app/storage/_sql/_storage.py:1132

                    SessionRow.user_id == user_id,
                )
                .values(team_id=team_id, updated_at=now),
            )
            await sess.commit()

    async def update_session_state(
        self,
        user_id: str,
        agent_id: str,
        session_id: str,
        state: AgentState,
    ) -> None:
        """Read-modify-write on the payload; raises if absent."""
        _ = user_id, agent_id  # scoping enforced by caller
        async with self._session() as sess:
            row = await sess.get(SessionRow, session_id)
            if row is None:
                raise KeyError(f"Session {session_id!r} not found.")
            record = _to_record(row, SessionRecord)
            record.state = state
            record.updated_at = _utcnow()
            new_row = _from_record(SessionRow, record)
            row.payload = new_row.payload
            row.updated_at = new_row.updated_at
            await sess.commit()

    async def list_sessions(
        self,
        user_id: str,
        agent_id: str,
    ) -> list[SessionRecord]:
        """Sessions for a (user, agent) pair — newest first."""
        from sqlalchemy import select

        async with self._session() as sess:
            rows = (

View on GitHub (pinned to e90f1c7592)

Solutions

1. Verify the session exists first with get_session(user_id, session_id) and create it if missing
2. Check for typos or truncated ids in the session_id passed in
3. If sessions expire, recreate the session and re-apply state instead of updating a dead one

Example fix

// before
await storage.update_session_state(sid, state)
// after
if await storage.get_session(uid, sid) is None:
    sid = await storage.create_session(uid, aid, SessionRecord(...))
await storage.update_session_state(sid, state)

if await storage.get_session(user_id, session_id) is None:\n    session_id = await storage.create_session(...)

try:\n    await storage.update_session_state(sid, state)\nexcept KeyError:\n    sid = await storage.create_session(...); await storage.update_session_state(sid, state)

When it happens

Trigger: Calling update_session_state(session_id, ...) for a session that was never created, was deleted, or whose id is misspelled; also after expiry-based cleanup removed the row.

Common situations: Using a stale session id after session expiry or deletion; resuming a conversation whose id came from old config; racing with a concurrent delete.

Related errors

• Session '{session_id}' not found.
• Session {session_id!r} already has an active chat run in thi
• Session {session_id!r} not found for agent {agent_id!r}.
• Knowledge base {knowledge_base_id!r} not found.
• Credential {record.data.embedding_model_config.credential_id

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/8ce0d6d7416b50a9. Report an issue: GitHub.