[v2]: handle target closed errors on popups (#1710)

# why
- some popups close so quickly that Stagehand tries to attach a CDP
session after the target is already gone, which produces unhandled
`Target.attachToTarget` / `newCDPSession` errors
- in the case of fast‑closing popups during auto‑init, we want to treat
“target gone” as a benign race instead of surfacing as failures
# what changed
- added shared “target gone” helpers in `lib/utils.ts`
- guarded CDP session creation to throw a targeted error when the
page/frame is already closed or detached
- swallowed that targeted error during page initialization and frame
listener attach only when the target is closed or the error indicates
the target is gone, so other CDP failures still surface


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Handle rapidly opening/closing popups by detecting “target gone”
scenarios and preventing CDP session attach errors. This reduces
flakiness during auto-init and keeps fast-closing popups from surfacing
as failures.

- **Bug Fixes**
- Added StagehandTargetClosedError and utils to detect closed/detached
targets and CDP “target gone” errors.
- Guarded CDP session creation and frame listener attach; swallow only
“target closed” errors during init.
- Removed cached CDP clients when targets are gone and skipped work on
already-closed pages/frames.

<sup>Written for commit 6143b9c.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1710">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Author: seanmcguire12

.changeset/humble-terms-wink.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+handle target closed errors on rapidly opening/closing popups

lib/StagehandContext.ts

@@ -7,6 +7,8 @@ import { Stagehand } from "./index";
 import { StagehandPage } from "./StagehandPage";
 import { Page } from "../types/page";
 import { EnhancedContext } from "../types/context";
+import { StagehandTargetClosedError } from "../types/stagehandErrors";
+import { isTargetGoneError } from "./utils";
 import { Protocol } from "devtools-protocol";
 import { scriptContent } from "./dom/build/scriptContent";
 
@@ -74,6 +76,9 @@ export class StagehandContext {
   private async createStagehandPage(
     page: PlaywrightPage,
   ): Promise<StagehandPage> {
+    if (page.isClosed()) {
+      throw new StagehandTargetClosedError();
+    }
     const stagehandPage = await new StagehandPage(
       page,
       this.stagehand,
@@ -121,10 +126,23 @@ export class StagehandContext {
     // Initialize existing pages
     const existingPages = context.pages();
     for (const page of existingPages) {
-      const stagehandPage = await instance.createStagehandPage(page);
+      if (page.isClosed()) continue;
+      let stagehandPage: StagehandPage | undefined;
+      try {
+        stagehandPage = await instance.createStagehandPage(page);
+      } catch (err) {
+        if (
+          err instanceof StagehandTargetClosedError ||
+          isTargetGoneError(err) ||
+          page.isClosed()
+        ) {
+          continue;
+        }
+        throw err;
+      }
       await instance.attachFrameNavigatedListener(page);
       // Set the first page as active
-      if (!instance.activeStagehandPage) {
+      if (!instance.activeStagehandPage && stagehandPage) {
         instance.setActivePage(stagehandPage);
       }
     }
@@ -179,9 +197,21 @@ export class StagehandContext {
   }
 
   private async handleNewPlaywrightPage(pwPage: PlaywrightPage): Promise<void> {
+    if (pwPage.isClosed()) return;
     let stagehandPage = this.pageMap.get(pwPage);
     if (!stagehandPage) {
-      stagehandPage = await this.createStagehandPage(pwPage);
+      try {
+        stagehandPage = await this.createStagehandPage(pwPage);
+      } catch (err) {
+        if (
+          err instanceof StagehandTargetClosedError ||
+          isTargetGoneError(err) ||
+          pwPage.isClosed()
+        ) {
+          return;
+        }
+        throw err;
+      }
     }
     this.setActivePage(stagehandPage);
   }
@@ -191,7 +221,14 @@ export class StagehandContext {
   ): Promise<void> {
     const shPage = this.pageMap.get(pwPage);
     if (!shPage) return;
-    const session: CDPSession = await this.intContext.newCDPSession(pwPage);
+    if (pwPage.isClosed()) return;
+    let session: CDPSession;
+    try {
+      session = await this.intContext.newCDPSession(pwPage);
+    } catch (err) {
+      if (pwPage.isClosed() || isTargetGoneError(err)) return;
+      throw err;
+    }
     await session.send("Page.enable");
 
     pwPage.once("close", () => {

lib/StagehandPage.ts

@@ -20,6 +20,7 @@ import { ActOptions, ActResult, GotoOptions, Stagehand } from "./index";
 import { LLMClient } from "./llm/LLMClient";
 import { StagehandContext } from "./StagehandContext";
 import { EncodedId, EnhancedContext } from "../types/context";
+import { isTargetGone, isTargetGoneError } from "./utils";
 import {
   StagehandError,
   StagehandNotInitializedError,
@@ -29,6 +30,7 @@ import {
   HandlerNotInitializedError,
   StagehandDefaultError,
   ExperimentalApiConflictError,
+  StagehandTargetClosedError,
 } from "../types/stagehandErrors";
 import { StagehandAPIError } from "@/types/stagehandApiErrors";
 import type { Protocol } from "devtools-protocol";
@@ -1049,13 +1051,26 @@ export class StagehandPage {
     target: PlaywrightPage | Frame = this.page,
   ): Promise<CDPSession> {
     const cached = this.cdpClients.get(target);
-    if (cached) return cached;
+    if (cached) {
+      if (isTargetGone(target)) {
+        this.cdpClients.delete(target);
+        throw new StagehandTargetClosedError();
+      }
+      return cached;
+    }
+
+    if (isTargetGone(target)) {
+      throw new StagehandTargetClosedError();
+    }
 
     try {
       const session = await this.context.newCDPSession(target);
       this.cdpClients.set(target, session);
       return session;
     } catch (err) {
+      if (isTargetGone(target) || isTargetGoneError(err)) {
+        throw new StagehandTargetClosedError(err);
+      }
       // Fallback for same-process iframes
       const msg = (err as Error).message ?? "";
       if (msg.includes("does not have a separate CDP session")) {

lib/utils.ts

@@ -6,6 +6,24 @@ import { LogLine } from "../types/log";
 import { ModelProvider } from "../types/model";
 import { ZodPathSegments } from "../types/stagehand";
 
+export const TARGET_GONE_ERROR_SNIPPETS = [
+  "No target with given id found",
+  "Target closed",
+];
+
+export function isTargetGoneError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return TARGET_GONE_ERROR_SNIPPETS.some((snippet) => msg.includes(snippet));
+}
+
+export function isTargetGone(target: {
+  isClosed?: () => boolean;
+  isDetached?: () => boolean;
+}): boolean {
+  if (typeof target.isClosed === "function" && target.isClosed()) return true;
+  return typeof target.isDetached === "function" && target.isDetached();
+}
+
 export function validateZodSchema(schema: z.ZodTypeAny, data: unknown) {
   const result = schema.safeParse(data);
 

types/stagehandErrors.ts

@@ -89,6 +89,21 @@ export class StagehandNotInitializedError extends StagehandError {
   }
 }
 
+export class StagehandTargetClosedError extends StagehandError {
+  public causedBy?: Error | StagehandError;
+
+  constructor(error?: unknown) {
+    const message =
+      error instanceof Error || error instanceof StagehandError
+        ? `Target closed before CDP session could attach: ${error.message}`
+        : "Target closed before CDP session could attach";
+    super(message);
+    if (error instanceof Error || error instanceof StagehandError) {
+      this.causedBy = error;
+    }
+  }
+}
+
 export class BrowserbaseSessionNotFoundError extends StagehandError {
   constructor() {
     super("No Browserbase session ID found");