Implementation:Webdriverio Webdriverio WebDriverRequestError

Knowledge Sources	Webdriverio_Webdriverio
Domains	WebDriver, Error_Handling
Last Updated	2026-02-12 00:00 GMT

Overview

The WebDriverRequestError module defines three error classes for handling WebDriver HTTP request and response failures, enriching error messages with command context including the executing command name and arguments.

Description

This module provides a hierarchy of three error classes. The abstract WebDriverError base class requires subclasses to provide url and opts properties, and offers a computeErrorMessage() method that extracts the command name from the URL path (using regex matching) and formats the error with method and arguments context. It uses private methods #getExecCmdName() (parsing the command name from the URL) and #getExecCmdArgs() (extracting and formatting the request body, with special handling for script execution commands).

WebDriverRequestError handles network-level failures (e.g., fetch failures, connection timeouts, DNS errors). It wraps the original error and enhances the message by: detecting fetch failed errors and providing actionable guidance, extracting error codes from the cause chain (handling both err.cause.code and err.code patterns), providing specific messages for UND_ERR_CONNECT_TIMEOUT, and extracting statusCode and body from the error cause.

WebDriverResponseError handles server-side failures where the HTTP request succeeded but the response indicates an error. It parses the response body through multiple layers (handling empty bodies, string bodies, object bodies with value fields), improves Chromedriver's "invalid locator" messages to include the actual selector used, and sets the error name from the response error field or detects stale element references.

Usage

Use these error classes in the request pipeline to wrap transport-level and protocol-level errors with rich contextual information. They are thrown by WebDriverRequest._libRequest() and WebDriverRequest._request().

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/webdriver/src/request/error.ts

Signature

abstract class WebDriverError extends Error {
    abstract url: URL
    abstract opts: RequestInit
    computeErrorMessage(): string
}

export class WebDriverRequestError extends WebDriverError {
    url: URL
    opts: RequestInit
    statusCode?: number
    body?: unknown
    code?: string

    constructor(err: Error, url: URL, opts: RequestInit)
}

export class WebDriverResponseError extends WebDriverError {
    url: URL
    opts: RequestInit

    constructor(response: unknown, url: URL, opts: RequestInit)
}

Import

import { WebDriverRequestError, WebDriverResponseError } from './request/error.js'

I/O Contract

Inputs

Name	Type	Required	Description
err (WebDriverRequestError)	`Error`	Yes	The original network/fetch error to wrap.
response (WebDriverResponseError)	`unknown`	Yes	The raw HTTP response object (with `body` and optional `statusCode`).
url	`URL`	Yes	The URL that was requested.
opts	`RequestInit`	Yes	The request options including method, body, and headers.

Outputs

Name	Type	Description
WebDriverRequestError	`Error` instance	Enhanced error with `message` including command name and args, plus optional `statusCode`, `body`, and `code` properties.
WebDriverResponseError	`Error` instance	Enhanced error with `name` set to the protocol error code and `message` including command context.

Usage Examples

import { WebDriverRequestError, WebDriverResponseError } from './request/error.js'

// Handling a network error
try {
    await fetch(url, opts);
} catch (err) {
    const wdError = new WebDriverRequestError(err as Error, url, opts);
    // wdError.message: 'WebDriverError: Request timed out! ... when running "navigateTo" with method "POST" and args ...'
    // wdError.code: 'UND_ERR_CONNECT_TIMEOUT'
    throw wdError;
}

// Handling an error response
const response = {
    statusCode: 404,
    body: { value: { error: 'no such element', message: 'Element not found' } }
};
const respError = new WebDriverResponseError(response, url, opts);
// respError.name: 'no such element'
// respError.message: 'WebDriverError: Element not found when running "findElement" ...'

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment