Enum SessionError 

pub enum SessionError {
    TabHung {
        target_id: Option<String>,
        url: Option<String>,
        timeout_ms: u64,
        hint: &'static str,
    },
    TabCrashed {
        target_id: String,
        reason: String,
    },
    TabNotFound {
        browser: String,
        name: String,
    },
    TargetGone {
        kind: TargetKind,
        details: String,
    },
    EngineUnsupported {
        tool: String,
        required_engine: String,
        current_engine: String,
        hint: &'static str,
    },
    SidecarConnectionFailed {
        tool: String,
        method: String,
        target_id: String,
        url: Option<String>,
        details: String,
        hint: &'static str,
    },
    RefUnknown {
        element: String,
        target_id: String,
    },
    StaleRef {
        element: String,
        target_id: String,
        reason: &'static str,
    },
    NodeGone {
        backend_node_id: u64,
        details: String,
    },
}

Typed errors raised from the page-session layer so callers (and tests) can pattern-match on the failure category — in particular, TabHung is the catch-all for the alive-but-unresponsive renderer case that has no protocol event signal.

Variants

TabHung

Op exceeded its per-call timeout without a reply and without a crash event. The most likely cause is a wedged renderer (service-worker suspended page, infinite loop, modal dialog, etc.). The agent should treat the tab as unusable until reloaded or recreated.

Fields

target_id: Option<String>

url: Option<String>

timeout_ms: u64

hint: &'static str

TabCrashed

Renderer crashed mid-op (observed via Target.targetCrashed / Inspector.targetCrashed). Distinct from TabHung so callers can distinguish “definitely dead” from “presumed wedged.”

Fields

target_id: String

reason: String

TabNotFound

<browser>/<name> referenced a tab that doesn’t exist in the tabs registry. Agents see this when they reference a tab they haven’t tab open’d yet — the recovery is to open it first. Distinct from TabHung because the tab was never there to wedge.

Fields

browser: String

name: String

TargetGone

Protocol-level error indicating the underlying target/session/context referenced by the request no longer exists in the browser. Raised by the CDP/BiDi client layer when the server returns a recognised “gone” code (e.g. no target with given id, no such frame). The recover-once wrappers treat this as a signal to recreate the tab and retry; otherwise it would surface as a generic protocol error.

Fields

kind: TargetKind

details: String

EngineUnsupported

The requested operation cannot run against the currently selected browser engine. Used by the Playwright sidecar tools (snapshot, click, type, etc.) when the active browser is BiDi (Firefox) — Playwright can’t drive a user-launched Firefox. The agent’s recovery is to browser_select a Chromium-family browser, or to use the engine-agnostic tools (browser_get_html, browser_fetch, browser_navigate, etc.) which work on both engines.

Fields

tool: String

required_engine: String

current_engine: String

hint: &'static str

SidecarConnectionFailed

A Playwright sidecar tool failed at the sidecar/CDP connection layer, but browser-control’s native backend was still able to wake and probe the target tab. This is intentionally distinct from TabHung: agents should not treat it as evidence that the page or app is stuck.

Fields

tool: String

method: String

target_id: String

url: Option<String>

details: String

hint: &'static str

RefUnknown

An element ref (e12) was passed that this tab’s ref table has never handed out. Refs come from browser_snapshot / browser_find; the agent must take one first.

Fields

element: String

target_id: String

StaleRef

A known ref no longer resolves: the page navigated (document token changed) or the node was removed. The agent must re-snapshot.

Fields

element: String

target_id: String

reason: &'static str

NodeGone

Native CDP input could not resolve a backendDOMNodeId (the node left the document). Mapped to SessionError::StaleRef by the tool layer, which knows the agent-facing ref.

Fields

backend_node_id: u64

details: String

Trait Implementations

impl Debug for SessionError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SessionError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for SessionError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.