{"record":{"id":"25d7e90d40029b71","repo":"musistudio/claude-code-router","slug":"a-valid-browser-automation-session-is-required","errorCode":null,"errorMessage":"A valid browser automation session is required.","messagePattern":"A valid browser automation session is required\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/electron/src/main/browser-automation-mcp.ts","lineNumber":1213,"sourceCode":"  }\n\n  private async createTab(args: Record<string, unknown>): Promise<unknown> {\n    const state = await this.ensureBrowserOpen();\n    const session = this.resolveOptionalSession(args);\n    this.assertCanMutate(session);\n    const previousActiveTabId = state.activeTabId;\n    const tab = builtInBrowserService.createAutomationTab(readString(args.url) || undefined);\n    if (args.activate === false && previousActiveTabId) {\n      builtInBrowserService.selectAutomationTab(previousActiveTabId);\n    }\n    const nextState = builtInBrowserService.getAutomationState();\n    return summarizeTab(requiredTabState(nextState, tab.id), nextState.activeTabId);\n  }\n\n  private requireSession(args: Record<string, unknown>): AttachedSession {\n    const session = this.resolveOptionalSession(args);\n    if (!session) {\n      throw new Error(\"A valid browser automation session is required.\");\n    }\n    return session;\n  }\n\n  private resolveOptionalSession(args: Record<string, unknown>): AttachedSession | undefined {\n    const ref = readSessionRef(args.session);\n    if (!ref) {\n      return undefined;\n    }\n    const existing = this.sessions.get(ref.sessionId);\n    if (existing) {\n      if (existing.ref.tabId !== ref.tabId) {\n        throw new Error(\"Browser automation session tabId does not match the attached session.\");\n      }\n      return existing;\n    }\n    const state = builtInBrowserService.getAutomationState();\n    if (!state.tabs.some((tab) => tab.id === ref.tabId)) {","sourceCodeStart":1195,"sourceCodeEnd":1231,"githubUrl":"https://github.com/musistudio/claude-code-router/blob/99f24806c6a2c660b16e53e95211c517448a6c90/packages/electron/src/main/browser-automation-mcp.ts#L1195-L1231","documentation":"Thrown by requireSession when resolveOptionalSession cannot produce an AttachedSession from the arguments. Some tools operate only in the context of an established automation session; passing no session object, or one whose ref fails to parse or resolve, triggers this error.","triggerScenarios":"Calling a session-scoped tool with arguments lacking a valid session field — the session value is not a record, has no usable sessionId/tabId, or the referenced session/tab lookup failed inside resolveOptionalSession.","commonSituations":"Scripts skip the attach/creation step and jump straight to a session-only tool; session state was cleared (e.g. tab closed removed its sessions) while the caller keeps the old ref.","solutions":["Run the tool that establishes the session first and echo its returned session object into subsequent calls.","Ensure the session object has valid sessionId and tabId fields.","If the tab was closed, re-create/re-attach the session before retrying."],"exampleFix":"// before\nawait call(\"browser_session_tool\", {});\n\n// after\nconst { session } = await call(\"browser_attach\", { tabId });\nawait call(\"browser_session_tool\", { session });","handlingStrategy":"validation","validationCode":"if (!isAttachedSession(args.session)) { const { session } = await call(\"browser_attach\", { tabId }); args.session = session; }\nawait call(sessionTool, args);","typeGuard":"function isAttachedSession(v: unknown): v is { ref: { sessionId: string; tabId: string } } { return typeof v === \"object\" && v !== null && typeof (v as any).ref?.sessionId === \"string\" && typeof (v as any).ref?.tabId === \"string\"; }","tryCatchPattern":"try { await call(sessionTool, args); } catch (e) { if (e instanceof Error && e.message.includes(\"valid browser automation session is required\")) { const { session } = await call(\"browser_attach\", { tabId }); await call(sessionTool, { ...args, session }); } else throw e; }","preventionTips":["Always run the attach step first","Echo returned session objects verbatim","Re-attach after tab close or restart"],"tags":["mcp","browser-automation","session","missing-param"],"backgroundTag":"session-not-found","analyzedSha":"99f24806c6a2c660b16e53e95211c517448a6c90","analyzedAt":"2026-08-27T04:11:01.184Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}