Shared browser not launched. Call createSharedSession() firs

Error message

Shared browser not launched. Call createSharedSession() first.

What it means

getSharedManager is the base-class hook that must return the shared Browser instance. The shared browser is only created by createSharedSession(); if shared-manager APIs are reached before that launch (or after destroy cleared sharedSession), the internal invariant is violated and this guard error is thrown.

Source

Thrown at browser/browser-viewer/src/thread-manager.ts:682

    await this.closeSharedBrowser();
  }

  /**
   * Get the manager for a session.
   * Required by base class.
   */
  protected getManagerForSession(session: ThreadSession): Browser {
    const viewerSession = session as BrowserViewerSession;
    return viewerSession.browser;
  }

  /**
   * Get the shared manager.
   * Required by base class.
   */
  protected getSharedManager(): Browser {
    if (!this.sharedSession) {
      throw new Error('Shared browser not launched. Call createSharedSession() first.');
    }
    return this.sharedSession.browser;
  }

  /**
   * Destroy a session and clean up resources.
   * Required by base class.
   */
  protected async doDestroySession(session: ThreadSession): Promise<void> {
    const viewerSession = this.getViewerSession(session.threadId);
    if (!viewerSession) {
      return;
    }
    await this.cleanupSession(viewerSession, session.threadId);
  }

  /**
   * Check if browser is running for a thread.

View on GitHub (pinned to 75dd419e61)

Solutions

Call createSharedSession() before any shared-browser operations.
Check shared-session readiness first and lazily create the session if absent.
Ensure destroy() isn't invoked before or during shared access.
Use thread-session methods instead of shared-manager APIs for thread-scoped browsers.

Example fix

// before
const browser = tm.getSharedManager(); // throws: not launched
// after
if (!tm.hasSharedSession?.()) {
  await tm.createSharedSession();
}
const browser = tm.getSharedManager();

Defensive patterns

Strategy: validation

Validate before calling

if (!tm.hasSharedSession?.()) {
  await tm.createSharedSession();
}
const browser = tm.getSharedManager(); // safe: shared session exists

Type guard

function sharedSessionReady(tm: { hasSharedSession?: () => boolean }): boolean {
  return tm.hasSharedSession ? tm.hasSharedSession() : false;
}

Try / catch

try {
  return tm.getSharedManager();
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Shared browser not launched')) {
    await tm.createSharedSession();
    return tm.getSharedManager();
  }
  throw err;
}

Prevention

Create the shared session during startup before any shared-browser access.
Expose and use a readiness check (e.g. hasSharedSession) before shared APIs.
Never access shared-manager methods after destroy() without re-creating the session.
Keep thread-scope and shared-scope APIs clearly separated to avoid cross-scope misuse.

When it happens

Trigger: Invoking shared-browser operations through getSharedManager before createSharedSession() was called, mixing shared-scope APIs into a thread-scoped manager, or accessing after destroy() cleared sharedSession.

Common situations: Lifecycle ordering bugs where shared APIs run before initialization completes; code assuming shared scope on a thread-scope manager; access during/after teardown.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/7d827b3c694640ea. Report an issue: GitHub.