Implementation:SeleniumHQ Selenium UnhandledAlertException

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

Overview

Concrete tool for signaling that an unexpected JavaScript alert was present during a WebDriver operation, provided by the Selenium WebDriver library.

Description

UnhandledAlertException is a Java class in the org.openqa.selenium package that extends WebDriverException. It is thrown when a WebDriver command encounters an unhandled JavaScript alert, confirm, or prompt dialog that blocks command execution.

Key features:

• Alert text capture -- the exception stores the text content of the unhandled alert, accessible via getAlertText().
• Composite message -- the constructor concatenates the error message and alert text (separated by ": ") for the parent exception message.
• Alert serialization -- the getAlert() method (annotated @Beta) returns an unmodifiable Map<String, String> containing the alert text under the key "text". This is used for wire-protocol serialization, as some drivers return alert text in this map format.
• Two constructors -- a single-argument form with just the message (alert text defaults to null) and a two-argument form with both message and alert text.

Usage

UnhandledAlertException is encountered when:

• The UnexpectedAlertBehaviour capability is set to ACCEPT_AND_NOTIFY or DISMISS_AND_NOTIFY, and an unexpected alert appears.
• A WebDriver command cannot complete because a modal dialog is blocking interaction.
• You need to detect and handle unexpected alerts in test automation by catching this specific exception.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: java/src/org/openqa/selenium/UnhandledAlertException.java

Signature

public class UnhandledAlertException extends WebDriverException {

    public UnhandledAlertException(String message)
    public UnhandledAlertException(String message, String alertText)

    public String getAlertText()

    @Beta
    public Map<String, String> getAlert()
}

Import

import org.openqa.selenium.UnhandledAlertException;

I/O Contract

Constructors

Constructor	Parameters	Description
UnhandledAlertException(String)	message -- error description	Creates an exception with the given message; alert text is null
UnhandledAlertException(String, String)	message -- error description, alertText -- the text of the unhandled alert	Creates an exception with the message and alert text; the parent message is set to message + ": " + alertText

Methods

Method	Input	Output	Description
getAlertText()	none	String	Returns the text of the unhandled alert dialog
getAlert()	none	Map<String, String> (unmodifiable)	Returns a map with key "text" mapped to the alert text; used for serialization. Annotated @Beta.

Inherited from WebDriverException

Method	Description
getMessage()	Returns the enriched message with system info, build info, and additional diagnostics
getRawMessage()	Returns the original message without enrichment
addInfo(String, String)	Adds custom diagnostic key-value pairs
getSystemInformation()	Returns OS and Java version info

Usage Examples

// Catching an unhandled alert exception
try {
    driver.findElement(By.id("submit")).click();
} catch (UnhandledAlertException e) {
    String alertText = e.getAlertText();
    System.out.println("Unexpected alert appeared: " + alertText);

    // Optionally dismiss the alert manually
    driver.switchTo().alert().dismiss();
}

// Using with ACCEPT_AND_NOTIFY behaviour
ChromeOptions options = new ChromeOptions();
options.setUnhandledPromptBehaviour(UnexpectedAlertBehaviour.ACCEPT_AND_NOTIFY);
WebDriver driver = new ChromeDriver(options);

try {
    driver.get("https://example.com/page-with-alert");
    driver.findElement(By.id("action")).click();
} catch (UnhandledAlertException e) {
    // Alert was auto-accepted, but we are notified
    System.out.println("Alert was accepted: " + e.getAlertText());
}

// Accessing the alert map (Beta API, used for serialization)
try {
    driver.findElement(By.id("trigger")).click();
} catch (UnhandledAlertException e) {
    Map<String, String> alertMap = e.getAlert();
    String text = alertMap.get("text"); // same as e.getAlertText()
}

Related Pages

• Implementation:SeleniumHQ_Selenium_WebDriverException -- parent class providing enriched exception diagnostics
• Implementation:SeleniumHQ_Selenium_UnexpectedAlertBehaviour -- the capability enum that controls when this exception is thrown
• Concept:WebDriver_Alert_Handling -- the alert handling model in Selenium WebDriver