[STG-710] Utilize custom error types

[sameelarif]

why

Custom error types allow for a better debugging experience. We used these error instances in V2 - just porting them over to our current codebase.

what changed

Implemented previously used error instance types into V3.

test plan

[changeset-bot]

🦋 Changeset detected

Latest commit: fcb82c7

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

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-evals	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

[greptile-apps]

Greptile Overview

Greptile Summary

This PR successfully ports custom error types from V2 to V3, replacing 30+ generic Error instances with specific, typed error classes. The changes improve error handling and debugging by providing clear, contextual error messages.

Key Changes

• Added CuaModelRequiredError to sdkErrors.ts for CUA model validation
• Replaced generic errors across 11 files with specific error types:
  • StagehandInvalidArgumentError for validation failures
  • StagehandNotInitializedError for lifecycle violations
  • MissingLLMConfigurationError for missing LLM setup
  • ExperimentalNotConfiguredError for feature conflicts
  • StagehandEvalError for script evaluation failures
  • StagehandElementNotFoundError for element resolution failures
  • ContentFrameNotFoundError for iframe resolution failures

Impact

• Better error categorization for error monitoring and debugging
• More actionable error messages with clear next steps
• Consistent error handling patterns across the codebase
• Type-safe error handling for consumers

The implementation is clean, consistent with existing error types, and maintains backward compatibility by extending the StagehandError base class.

Confidence Score: 5/5

• This PR is safe to merge - it's a straightforward refactoring that improves error handling without changing functionality
• The changes are well-structured, consistent, and low-risk. All error replacements maintain the same error behavior while providing better error categorization. No logical changes to the code paths, only error type improvements.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/lib/v3/types/public/sdkErrors.ts	5/5	Added CuaModelRequiredError for CUA model validation - clean implementation consistent with existing error types
packages/core/lib/v3/understudy/page.ts	5/5	Replaced 5 generic errors with StagehandInvalidArgumentError and StagehandEvalError for better error handling
packages/core/lib/v3/understudy/locator.ts	5/5	Replaced 7 generic errors with specific error types (StagehandElementNotFoundError, StagehandInvalidArgumentError) for improved error clarity
packages/core/lib/v3/v3.ts	5/5	Replaced 15+ generic errors with specific error types for initialization, validation, and configuration errors

Sequence Diagram

sequenceDiagram
    participant User
    participant V3
    participant Handler
    participant Understudy
    participant CustomError

    User->>V3: Call act/extract/observe/agent
    
    alt Missing Configuration
        V3->>CustomError: throw MissingLLMConfigurationError
        CustomError-->>User: Clear error with actionable message
    else Invalid Argument
        V3->>CustomError: throw StagehandInvalidArgumentError
        CustomError-->>User: Error details with validation info
    else Not Initialized
        V3->>CustomError: throw StagehandNotInitializedError
        CustomError-->>User: Instruction to call init()
    else Experimental Feature Conflict
        V3->>CustomError: throw ExperimentalNotConfiguredError
        CustomError-->>User: Configuration guidance
    end

    User->>Handler: Execute operation
    
    alt Element Not Found
        Handler->>Understudy: Resolve element
        Understudy->>CustomError: throw StagehandElementNotFoundError
        CustomError-->>User: XPath/selector details
    else Evaluation Failed
        Handler->>Understudy: Evaluate script
        Understudy->>CustomError: throw StagehandEvalError
        CustomError-->>User: Evaluation error details
    else Invalid Input
        Understudy->>CustomError: throw StagehandInvalidArgumentError
        CustomError-->>User: Input validation error
    end

    Note over User,CustomError: All errors extend StagehandError base class
    Note over User,CustomError: Provides consistent error handling and debugging

Loading

[greptile-apps]

_{11 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}