{"record":{"id":"929470c17a176e2e","repo":"mastra-ai/mastra","slug":"unknown-acp-sessionid-sessionid","errorCode":null,"errorMessage":"Unknown ACP sessionId: ${sessionId}","messagePattern":"Unknown ACP sessionId: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/acp/agent.ts","lineNumber":35,"sourceCode":"\n/**\n * ACP Agent implementation that wraps a mastracode Controller.\n * Each instance represents one ACP connection from a client.\n */\nexport class MastraCodeAcpAgent implements Agent {\n  private readonly connection: AgentSideConnection;\n  private readonly controller: AgentController;\n  private readonly session: Session;\n  private readonly modes: AgentControllerMode[];\n  private readonly unsubscribeSessionEvents: () => void;\n  private readonly sessionMap = new Map<string, string>(); // sessionId -> threadId\n  private currentPromptState: PromptState | null = null;\n  private promptMutex: Promise<void> = Promise.resolve();\n\n  private getThreadIdOrThrow(sessionId: string): string {\n    const threadId = this.sessionMap.get(sessionId);\n    if (!threadId) {\n      throw new Error(`Unknown ACP sessionId: ${sessionId}`);\n    }\n    return threadId;\n  }\n\n  constructor(\n    connection: AgentSideConnection,\n    controller: AgentController,\n    session: Session,\n    modes: AgentControllerMode[],\n  ) {\n    this.connection = connection;\n    this.controller = controller;\n    this.session = session;\n    this.modes = modes;\n\n    // Register persistent event listener\n    this.unsubscribeSessionEvents = this.session.subscribe(event => {\n      handleAgentControllerEvent(event, this.currentPromptState, this.connection, this.session);","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/acp/agent.ts#L17-L53","documentation":"The ACP agent keeps a sessionMap from ACP sessionId to Mastra threadId. Any prompt or notification referencing a sessionId that was never established via `newSession` (or whose mapping was lost) makes getThreadIdOrThrow throw 'Unknown ACP sessionId'.","triggerScenarios":"Any ACP RPC (prompt, cancel, session updates) calls `threadId(sessionId)` for a sessionId absent from `this.sessionMap` — e.g. the client sends a prompt for a session created in a previous process lifetime or never created via newSession.","commonSituations":"Client reconnects and reuses stale session ids after the agent process restarted; client bug sending an unopened session id; in-memory sessionMap lost on restart since it is not persisted.","solutions":["Ensure the client calls newSession and uses the returned sessionId for subsequent requests","Recreate the session via newSession after an agent restart instead of reusing old ids","Log the sessionMap keys on failure to spot id mismatch/stale ids","Check the client is not fabricating or truncating session ids"],"exampleFix":"// before\nawait agent.prompt({ sessionId: 'stale-session-id', prompt: [...] });\n// after\nconst { sessionId } = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });\nawait agent.prompt({ sessionId, prompt: [...] });","handlingStrategy":"type-guard","validationCode":"if (!sessionMap.has(sessionId)) {\n  throw new Error(`session ${sessionId} not open; call newSession first`);\n}","typeGuard":"const isKnownSession = (agent: AcpAgent, sessionId: string): boolean =>\n  agent.hasSession(sessionId);","tryCatchPattern":"try {\n  const threadId = agent.threadId(sessionId);\n} catch (err) {\n  if ((err as Error).message.startsWith('Unknown ACP sessionId')) {\n    const { sessionId: fresh } = await agent.newSession({ cwd: process.cwd() });\n    // retry with fresh session\n  } else throw err;\n}","preventionTips":["Always create sessions via newSession and persist the returned id","Re-create sessions after agent process restarts","Track session lifecycle client-side and drop ids after close"],"tags":["acp","session-state","state-management"],"backgroundTag":"unknown-session-id","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}