{"record":{"id":"6c7100aa6c4039c6","repo":"mastra-ai/mastra","slug":"browser-not-launched-6c7100","errorCode":null,"errorMessage":"Browser not launched","messagePattern":"Browser not launched","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"browser/stagehand/src/stagehand-browser.ts","lineNumber":458,"sourceCode":"      await this.threadManager.getManagerForThread(threadId);\n      stagehand = this.threadManager.getExistingManagerForThread(threadId);\n    }\n\n    return stagehand ?? null;\n  }\n\n  /**\n   * Require a Stagehand instance for the given or current thread.\n   * Throws if no instance is available.\n   * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()\n   *                           Use this to avoid race conditions in concurrent tool calls.\n   */\n  private requireStagehand(explicitThreadId?: string): Stagehand {\n    const threadId = explicitThreadId ?? this.getCurrentThread();\n    const stagehand = this.threadManager.getExistingManagerForThread(threadId) ?? this.sharedManager;\n\n    if (!stagehand) {\n      throw new Error('Browser not launched');\n    }\n    return stagehand;\n  }\n\n  /**\n   * Get the current page from Stagehand v3, respecting thread scope.\n   * @param explicitThreadId - Optional thread ID to use instead of getCurrentThread()\n   *                           Use this to avoid race conditions in concurrent tool calls.\n   */\n  private getPage(explicitThreadId?: string): V3Page | null {\n    const scope = this.getScope();\n    const threadId = explicitThreadId ?? this.getCurrentThread();\n\n    // For 'thread' scope, get the thread's Stagehand's active page\n    if (scope === 'thread' && threadId && threadId !== DEFAULT_THREAD_ID) {\n      const stagehand = this.threadManager.getExistingManagerForThread(threadId);\n      if (stagehand?.context) {\n        return stagehand.context.activePage() as V3Page | null;","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/browser/stagehand/src/stagehand-browser.ts#L440-L476","documentation":"requireStagehand resolves the Stagehand instance for the current thread, falling back to the shared manager. If neither a thread-scoped manager nor a shared manager exists, no browser was ever launched, so any Stagehand-dependent operation cannot proceed and the library throws. It is a guard ensuring you cannot interact with a browser that does not exist.","triggerScenarios":"Calling the public stagehand accessor (or methods that route through requireStagehand, like getPage/actions) before calling launch/connect, or after the browser was closed such that no manager remains.","commonSituations":"Forgetting to await browser launch at startup; calling the browser from a different thread scope where only thread-scoped sessions exist; using a StagehandBrowser after close()/disconnect; race where launch failed silently upstream.","solutions":["Call launch()/connect() on the StagehandBrowser before using it","Check that prior launch did not fail (it throws its own error) and that no early close() ran","If using thread scope, operate from a thread that has an active session or rely on the shared manager","Verify initialization order in your app lifecycle (e.g. launch in startup hook)"],"exampleFix":"// before\nconst page = await browser.stagehand().page;\n// after\nawait browser.launch();\nconst page = await browser.stagehand().page;","handlingStrategy":"try-catch","validationCode":"if (!browser.isBrowserRunning()) {\n  await browser.launch();\n}","typeGuard":null,"tryCatchPattern":"try {\n  const stagehand = browser.stagehand();\n} catch (e) {\n  if (e instanceof Error && e.message === 'Browser not launched') {\n    await browser.launch();\n  } else throw e;\n}","preventionTips":["Launch the browser in an awaited startup path before any usage","Check isBrowserRunning() before operations after long idle periods","Ensure close()/disconnect() is not called while operations are pending","Track browser lifecycle in a central manager, not ad-hoc call sites"],"tags":["browser","lifecycle","initialization","stagehand"],"backgroundTag":"browser-not-launched","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}