Implementation:SeleniumHQ Selenium WebDriverException

Knowledge Sources	SeleniumHQ_Selenium Selenium Documentation
Domains	WebDriver, Browser_Automation
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for representing errors that occur during WebDriver operations, provided by the Selenium WebDriver library.

Description

WebDriverException is a Java class in the org.openqa.selenium package that extends RuntimeException and serves as the base exception class for all Selenium WebDriver errors. It enriches standard exception messages with diagnostic context including build information, system information (OS name, architecture, version, Java version), host information (hostname, IP), and custom additional information.

Key features:

Enriched messages -- the overridden getMessage() method appends build info, system info, and additional info to the original message. This behavior is suppressed when the cause is itself a WebDriverException, preventing duplicate information in chained exceptions.
Support URL -- subclasses can override getSupportUrl() to provide a link to Selenium troubleshooting documentation. The base class returns null; the base support URL is https://www.selenium.dev/documentation/webdriver/troubleshooting/errors.
Extra info map -- a ConcurrentHashMap-backed map allows adding arbitrary key-value diagnostic pairs via addInfo(String, String).
Driver detection -- the static getDriverName(StackTraceElement[]) method inspects the stack trace to identify which WebDriver implementation triggered the exception.
Constants -- SESSION_ID and DRIVER_INFO are well-known keys for the extra info map.

Usage

WebDriverException is used as:

The root of the Selenium exception hierarchy -- all specific WebDriver exceptions (e.g., NoSuchElementException, TimeoutException, UnhandledAlertException) extend it.
A catch-all for any WebDriver error when you want to handle all Selenium failures uniformly.
A diagnostic aid -- the enriched message provides system and driver context that helps debug failures in CI or remote environments.

Code Reference

Source Location

Repository: SeleniumHQ_Selenium
File: java/src/org/openqa/selenium/WebDriverException.java

Signature

public class WebDriverException extends RuntimeException {

    public static final String SESSION_ID = "Session ID";
    public static final String DRIVER_INFO = "Driver info";
    protected static final String BASE_SUPPORT_URL =
        "https://www.selenium.dev/documentation/webdriver/troubleshooting/errors";

    public WebDriverException()
    public WebDriverException(String message)
    public WebDriverException(Throwable cause)
    public WebDriverException(String message, Throwable cause)

    public String getMessage()
    public String getRawMessage()
    public String getSystemInformation()
    public static String getHostInformation()
    public String getSupportUrl()
    public BuildInfo getBuildInformation()
    public static String getDriverName(StackTraceElement[] stackTraceElements)
    public void addInfo(String key, String value)
    public String getAdditionalInformation()
}

Import

import org.openqa.selenium.WebDriverException;

I/O Contract

Constructors
Constructor	Parameters	Description
`WebDriverException()`	none	Creates an exception with no message or cause
`WebDriverException(String)`	`message` (nullable)	Creates an exception with the given message
`WebDriverException(Throwable)`	`cause` (nullable)	Creates an exception wrapping the given cause
`WebDriverException(String, Throwable)`	`message` (nullable), `cause` (nullable)	Creates an exception with both message and cause

Key Methods
Method	Input	Output	Description
`getMessage()`	none	`String` (nullable)	Returns the enriched message including build, system, and additional info. If the cause is a WebDriverException, returns only the raw message to avoid duplication.
`getRawMessage()`	none	`String` (nullable)	Returns the original message without enrichment
`getSystemInformation()`	none	`String`	Returns formatted OS and Java version info
`getHostInformation()`	none	`String`	Static method returning formatted hostname and IP address
`getSupportUrl()`	none	`String` (nullable)	Returns a URL to troubleshooting docs; base class returns null
`getBuildInformation()`	none	`BuildInfo`	Returns the Selenium build information object
`getDriverName(StackTraceElement[])`	`StackTraceElement[]`	`String`	Static method that inspects the stack trace to find the driver class name; returns "unknown" if not found
`addInfo(String, String)`	`key`, `value`	void	Adds a key-value pair to the additional info map
`getAdditionalInformation()`	none	`String`	Returns all additional info entries as a newline-separated string

Constants
Constant	Value	Description
`SESSION_ID`	`"Session ID"`	Key for session ID in the extra info map
`DRIVER_INFO`	`"Driver info"`	Key for driver info in the extra info map
`BASE_SUPPORT_URL`	`"https://www.selenium.dev/documentation/webdriver/troubleshooting/errors"`	Base URL for Selenium troubleshooting documentation

Usage Examples

// Catching WebDriverException as a catch-all
try {
    WebDriver driver = new ChromeDriver();
    driver.get("https://example.com");
    driver.findElement(By.id("nonexistent")).click();
} catch (WebDriverException e) {
    // getMessage() includes system info, build info, and driver info
    System.err.println(e.getMessage());

    // getRawMessage() returns only the original error message
    System.err.println("Raw: " + e.getRawMessage());
}

// Adding custom diagnostic info
try {
    driver.findElement(By.id("submit")).click();
} catch (WebDriverException e) {
    e.addInfo("Session ID", "abc-123");
    e.addInfo("Page URL", driver.getCurrentUrl());
    throw e;  // re-throw with enriched diagnostics
}

// Throwing a WebDriverException with a cause
try {
    // some operation
} catch (IOException ioEx) {
    throw new WebDriverException("Failed to communicate with browser", ioEx);
}

Related Pages

Implementation:SeleniumHQ_Selenium_UnhandledAlertException -- a specific subclass for unhandled alert errors
Implementation:SeleniumHQ_Selenium_PageLoadStrategy -- configuration that affects when navigation exceptions may occur
Concept:WebDriver_Exception_Hierarchy -- the overall exception hierarchy in Selenium

Page Connections

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

Principle

Implementation

Heuristic

Environment