agentscope-ai/agentscope · error · HTTPException

Session {session_id!r} not found for agent {agent_id!r}.

Error message

Session {session_id!r} not found for agent {agent_id!r}.

What it means

Raised by ChatService._run_impl when storage.get_session returns None for the (user_id, agent_id, session_id) triple during a run. Unlike the agent check, this 404 names the session explicitly, telling the caller the session no longer exists for that agent. Runs must target an existing session; continuation of a vanished session is rejected.

Source

Thrown at src/agentscope/app/_service/_chat.py:696

                # the agent is not visible to the caller.
                # -------------------------------------------------------------
                try:
                    agent_record = await self._access.resolve_agent(
                        user_id,
                        agent_id,
                    )
                except HTTPException as exc:
                    raise HTTPException(
                        status_code=404,
                        detail=f"Agent {agent_id!r} not found.",
                    ) from exc
                session_record = await self._storage.get_session(
                    user_id,
                    agent_id,
                    session_id,
                )
                if session_record is None:
                    raise HTTPException(
                        status_code=404,
                        detail=(
                            f"Session {session_id!r} not found for "
                            f"agent {agent_id!r}."
                        ),
                    )
                worker_name = agent_record.data.name

                # -------------------------------------------------------------
                # 1b. Resolve the team identity ONCE, before anything that
                # can fail: a worker whose assembly dies still has to reach
                # its leader. Downstream consumers reuse this.
                # -------------------------------------------------------------
                if session_record.team_id is not None:
                    team = await self._storage.get_team(
                        user_id,
                        session_record.team_id,
                    )

View on GitHub (pinned to e90f1c7592)

Solutions

1. Create a new session (fresh run without session_id) when this 404 is returned, and persist the new id
2. Verify the session belongs to the same agent_id being run
3. Shorten the gap between session creation and use, or extend session TTL if expiry is the cause
4. Clear cached session ids on agent switch in the client

Example fix

// before
await client.run(agent_id, session_id="sess-old", ...);  // 404
// after
try:
    run = await client.run(agent_id, session_id="sess-old", ...);
except NotFoundError:
    run = await client.run(agent_id, ...);  // new session
    save_session(run.session_id);

session = await storage.get_session(user_id, agent_id, session_id)
if session is None:
    session_id = None  # force new session
await client.run(agent_id=agent_id, session_id=session_id, ...)

try:
    run = await client.run(agent_id, session_id=session_id, ...)
except NotFoundError:
    run = await client.run(agent_id, ...)  # start fresh session
    persist(run.session_id)

When it happens

Trigger: Calling run with a session_id that was deleted, expired, or belongs to a different agent or user. Typical after session cleanup, switching agents mid-conversation, or resuming from stale persisted state.

Common situations: Frontend keeps a session_id in localStorage after server-side session GC; user switches agent in the UI but keeps the old session id; test fixtures reuse session ids across runs; multi-instance deployments where session data wasn't shared.

Related errors

• Session {session_id!r} already has an active chat run in thi
• Agent {agent_id!r} not found.
• Channel '{channel_id}' not found.
• Session '{session_id}' not found.
• No model configuration found for agent {agent_id}

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