[fix]: handle CBOR stack limit errors #1424

seanmcguire12 · 2025-12-16T20:14:44Z

why

when running on a site with deep nesting of elements/nodes, the captureHybridSnapshot() will fail and log this error:
Error: -32000 Failed to convert response to JSON: CBOR: stack limit exceeded at position 60578
this is because Dom.getDocument fails

what changed

added handling and retries to Dom.getDocument where we exponentially reduce the depth parameter on each retry

test plan

added an e2e test nested-div.spec.ts just to confirm the captureHybridSnapshot() fn does not throw on the test website
added unit tests in snapshot-cbor.test.ts which use mock data to confirm that (1) retries are actually happening when depth is exceeded, (2) after a failed step, missing nodes are glued back into the tree, and (3) the StagehandDomProcessError is thrown when all depth attempts have failed

Summary by cubic

Prevent CBOR “stack limit exceeded” errors in captureHybridSnapshot and DOM map building on deeply nested pages. Adapt DOM depth and hydrate missing nodes so snapshots complete reliably.

Bug Fixes
- Added adaptive retries for DOM.getDocument with reducing depth.
- Hydrated truncated trees via DOM.describeNode with fallback depths; merged children/shadow roots/contentDocument.
- Threw StagehandDomProcessError with a clear message when all attempts fail.
- Tests: e2e to confirm no throw on a deeply nested site; unit tests for retries, hydration, and failure path.

^{Written for commit b11476a. Summary will update automatically on new commits.}

changeset-bot · 2025-12-16T20:14:48Z

🦋 Changeset detected

Latest commit: b11476a

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

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

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

cubic-dev-ai

No issues found across 4 files

greptile-apps · 2025-12-16T20:21:15Z

Greptile Overview

Greptile Summary

This PR fixes a critical CBOR stack limit error that occurs when Stagehand's captureHybridSnapshot() function encounters deeply nested DOM structures. The issue manifests as -32000 Failed to convert response to JSON: CBOR: stack limit exceeded errors when Dom.getDocument tries to serialize very deep element trees.

The fix implements an adaptive retry mechanism that progressively reduces the depth parameter from -1 down to 1 when CBOR errors occur. When DOM traversal is limited by depth, a hydration system uses Dom.describeNode to patch missing children, shadow roots, and content documents back into the truncated tree. This ensures reliable snapshot collection across diverse web content while gracefully handling edge cases.

The implementation integrates with Stagehand's existing DOM processing pipeline by replacing direct Dom.getDocument calls with the new getDomTreeWithFallback function in both buildSessionDomIndex and domMapsForSession.

Important Files Changed

Filename	Score	Overview
packages/core/lib/v3/understudy/a11y/snapshot.ts	4/5	Core fix implementing adaptive retry logic and DOM hydration system for CBOR stack limit errors
packages/core/tests/snapshot-cbor.test.ts	5/5	Comprehensive unit tests validating retry behavior, error handling, and node hydration
packages/core/lib/v3/tests/nested-div.spec.ts	4/5	E2E test ensuring captureHybridSnapshot works on deeply nested test pages

Confidence score: 4/5

This PR addresses a well-defined edge case with a targeted solution that maintains backward compatibility
Score reflects solid implementation with comprehensive test coverage, but complexity of DOM tree manipulation introduces some risk
Pay close attention to the snapshot.ts file's retry logic and hydration mechanisms for potential edge cases

Sequence Diagram

sequenceDiagram
    participant User
    participant StagehandAPI as "Stagehand API"
    participant CDPSession as "CDP Session"
    participant Browser as "Browser DOM"

    User->>StagehandAPI: "Call captureHybridSnapshot(page)"
    StagehandAPI->>CDPSession: "Enable DOM, Runtime, Accessibility"
    CDPSession->>Browser: "Enable protocols"
    
    StagehandAPI->>StagehandAPI: "Call getDomTreeWithFallback(session, pierce=true)"
    
    loop "DOM Depth Attempts [-1, 256, 128, 64, 32, 16, 8, 4, 2, 1]"
        StagehandAPI->>CDPSession: "DOM.getDocument({depth: currentDepth})"
        CDPSession->>Browser: "Request DOM tree with depth limit"
        Browser-->>CDPSession: "Error: CBOR stack limit exceeded"
        CDPSession-->>StagehandAPI: "CBOR stack limit error"
        StagehandAPI->>StagehandAPI: "Check if CBOR error, continue to next depth"
    end
    
    Note over StagehandAPI: "Eventually succeeds with reduced depth (e.g., 256)"
    CDPSession->>Browser: "DOM.getDocument({depth: 256})"
    Browser-->>CDPSession: "Truncated DOM tree"
    CDPSession-->>StagehandAPI: "DOM tree with missing children"
    
    StagehandAPI->>StagehandAPI: "Call hydrateDomTree(session, root, pierce)"
    
    loop "For each node needing expansion"
        StagehandAPI->>StagehandAPI: "Check shouldExpandNode(node)"
        alt "Node has more children than returned"
            loop "Describe Depth Attempts [-1, 64, 32, 16, 8, 4, 2, 1]"
                StagehandAPI->>CDPSession: "DOM.describeNode({nodeId/backendNodeId, depth})"
                CDPSession->>Browser: "Get expanded node details"
                alt "CBOR error again"
                    Browser-->>CDPSession: "Error: CBOR stack limit exceeded"
                    CDPSession-->>StagehandAPI: "CBOR stack limit error"
                    StagehandAPI->>StagehandAPI: "Try next smaller depth"
                else "Success"
                    Browser-->>CDPSession: "Expanded node with children"
                    CDPSession-->>StagehandAPI: "Complete node details"
                    StagehandAPI->>StagehandAPI: "mergeDomNodes(target, source)"
                end
            end
        end
    end
    
    StagehandAPI->>CDPSession: "Accessibility.getFullAXTree()"
    CDPSession->>Browser: "Get accessibility tree"
    Browser-->>CDPSession: "Accessibility nodes"
    CDPSession-->>StagehandAPI: "A11y tree data"
    
    StagehandAPI->>StagehandAPI: "Build combined tree with XPath mapping"
    StagehandAPI-->>User: "Return HybridSnapshot with combinedTree, XPath maps"

greptile-apps

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

packages/core/lib/v3/tests/nested-div.spec.ts

packages/core/lib/v3/understudy/a11y/snapshot.ts

pirate

tenatively approve this PR, but it could use some more docstrings/comments explaining the logic flow / why these steps are necessary (in the code next to the logic, not just as PR comments).

also worth explaining how it interacts with iframes on different origins across a page, shadow doms, etc.

@tkattkat

handle CBOR stack limit errors

1e5fa7a

cubic-dev-ai bot reviewed Dec 16, 2025

View reviewed changes

greptile-apps bot reviewed Dec 16, 2025

View reviewed changes

packages/core/lib/v3/tests/nested-div.spec.ts Show resolved Hide resolved

pirate reviewed Dec 17, 2025

View reviewed changes

packages/core/lib/v3/understudy/a11y/snapshot.ts Show resolved Hide resolved

pirate approved these changes Dec 17, 2025

View reviewed changes

add comments

b11476a

seanmcguire12 merged commit a890f16 into main Dec 17, 2025
15 checks passed

This was referenced Dec 16, 2025

Version Packages #1414

Merged

Version Packages CloudEngineHub/stagehand#1

Open

Version Packages kenchikuliu/stagehand#1

Open

Version Packages shaneholloman/stagehand#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[fix]: handle CBOR stack limit errors #1424

[fix]: handle CBOR stack limit errors #1424

Uh oh!

seanmcguire12 commented Dec 16, 2025 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Dec 16, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

greptile-apps bot commented Dec 16, 2025

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Uh oh!

pirate left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

[fix]: handle CBOR stack limit errors #1424

[fix]: handle CBOR stack limit errors #1424

Uh oh!

Conversation

seanmcguire12 commented Dec 16, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

why

what changed

test plan

Summary by cubic

Uh oh!

changeset-bot bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot commented Dec 16, 2025

Greptile Overview

Greptile Summary

Important Files Changed

Confidence score: 4/5

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pirate left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seanmcguire12 commented Dec 16, 2025 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Dec 16, 2025 •

edited

Loading

pirate left a comment •

edited

Loading