[v2]: handle target closed errors on popups

[seanmcguire12]

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

---

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.

^{Written for commit 6143b9c. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 6143b9c

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Summary

This PR addresses race conditions with fast-closing popups by adding graceful error handling for CDP session attachment failures.

Key Changes:

• Added utility functions (isTargetGoneError, isTargetGone) to detect closed/detached targets
• Introduced StagehandTargetClosedError for targeted error handling
• Protected page initialization in StagehandContext.init() with try-catch blocks that swallow target-gone errors
• Guarded CDP session creation in getCDPClient() and attachFrameNavigatedListener() to check if targets are closed before and after operations
• All defensive checks treat target-closed scenarios as benign during auto-initialization while preserving other CDP errors

The implementation correctly handles the race condition where popups close before Stagehand can attach CDP sessions, treating these as expected outcomes rather than failures.

Confidence Score: 5/5

• Safe to merge - well-designed defensive error handling with no breaking changes
• The PR implements robust error handling for a specific race condition without introducing breaking changes or security issues. The code follows existing patterns, adds appropriate error types, and correctly distinguishes between expected target-closed scenarios and genuine errors that should surface.
• No files require special attention

Important Files Changed

Filename	Overview
.changeset/humble-terms-wink.md	Standard changeset file documenting the patch-level fix for popup target closed errors
lib/utils.ts	Added helper functions isTargetGoneError and isTargetGone to detect closed/detached targets
types/stagehandErrors.ts	Added StagehandTargetClosedError class with optional causedBy field for chaining underlying errors
lib/StagehandContext.ts	Added defensive checks and graceful error handling for closed pages during initialization and CDP session creation
lib/StagehandPage.ts	Enhanced getCDPClient to check target status before and after CDP operations and throw appropriate errors

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Popup Opens] --> B{Page Already Closed?}
    B -->|Yes| C[Skip Initialization]
    B -->|No| D[Create StagehandPage]
    
    D --> E{Page Closed During Init?}
    E -->|Yes - StagehandTargetClosedError| F[Catch and Continue]
    E -->|Yes - isTargetGoneError| F
    E -->|Yes - page.isClosed| F
    E -->|No| G[Page Initialized]
    
    G --> H[Attach CDP Session]
    H --> I{Target Still Available?}
    I -->|No| J[Return Early]
    I -->|Yes| K[Create CDP Session]
    
    K --> L{CDP Session Created?}
    L -->|Error - Target Gone| M[Catch and Return]
    L -->|Error - Other| N[Re-throw Error]
    L -->|Success| O[Session Attached]
    
    F --> P[Continue Without Page]
    M --> P
    P --> Q[Normal Operation]
    O --> Q

Loading

_{Last reviewed commit: 6143b9c}

[greptile-apps]

_{5 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant B as Browser (Playwright)
    participant C as StagehandContext
    participant P as StagehandPage
    participant U as Utils

    Note over B,U: Initialization / New Popup Detected

    C->>B: Detect new page/popup
    
    C->>B: NEW: page.isClosed()
    alt Page is already gone
        C-->>C: Skip initialization
    else Page active
        C->>P: createStagehandPage(pwPage)
        
        P->>U: NEW: isTargetGone(pwPage)
        U-->>P: false

        P->>C: getCDPSession()
        
        C->>B: Playwright: newCDPSession()
        
        alt CHANGED: Race Condition (Popup closes during attach)
            B-->>C: Error ("Target closed" / "No target with id")
            C-->>P: Error
            P->>U: NEW: isTargetGoneError(err)
            U-->>P: true
            P-->>C: Throw StagehandTargetClosedError
            
            Note over C: NEW: Catch/Swallow during Init
            C->>C: Log & Continue (Treat as benign)
        else Success Path
            B-->>C: CDPSession
            C-->>P: CDPSession
            P->>P: Cache CDPSession
            P-->>C: StagehandPage instance
        end
    end

    Note over B,U: Subsequent Page Operations

    P->>P: getCDPSession()
    P->>U: NEW: Check cache & isTargetGone()
    opt NEW: Target gone but session was cached
        P->>P: Remove from cdpClients cache
        P-->>C: Throw StagehandTargetClosedError
    end

    C->>B: CHANGED: attachFrameNavigatedListener(pwPage)
    alt NEW: Page closes before listener attach
        C->>B: pwPage.newCDPSession()
        B-->>C: Error (Target gone)
        C->>U: isTargetGoneError(err)
        U-->>C: true
        C-->>C: Gracefully exit listener setup
    end

Loading