Selenium Exception Handling

Web pages change constantly. An element that existed yesterday might move, disappear, or load slower today. Selenium throws specific exception types when something unexpected happens, and understanding each one speeds up debugging.

Diagram: Common Exception Triggers

Action Attempted            Exception Thrown
------------------          -------------------
Element not found       --> NoSuchElementException
Element not visible     --> ElementNotInteractableException
Page takes too long     --> TimeoutException
Element removed mid-use --> StaleElementReferenceException
No alert present        --> NoAlertPresentException

NoSuchElementException

This occurs when findElement() cannot locate any matching element on the page. A typo in the locator, an unloaded page, or a genuinely missing element all trigger this error.

try {
    driver.findElement(By.id("wrong-id")).click();
} catch (NoSuchElementException e) {
    System.out.println("Element was not found on the page.");
}

ElementNotInteractableException

This occurs when an element exists in the HTML but cannot accept interaction, often because it sits behind another element or remains hidden through CSS.

try {
    driver.findElement(By.id("hidden-btn")).click();
} catch (ElementNotInteractableException e) {
    System.out.println("Element exists but cannot be clicked right now.");
}

StaleElementReferenceException

This occurs when a page refreshes or updates after you located an element, making your saved reference point to nothing. Re-locating the element right before use fixes this error reliably.

WebElement element = driver.findElement(By.id("dynamic-item"));
driver.navigate().refresh();
try {
    element.click();
} catch (StaleElementReferenceException e) {
    element = driver.findElement(By.id("dynamic-item"));
    element.click();
}

TimeoutException

This occurs when an explicit wait condition never becomes true within the given time limit.

try {
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(5));
    wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("slow-element")));
} catch (TimeoutException e) {
    System.out.println("Element did not appear within the time limit.");
}

Using try-catch-finally

try {
    driver.findElement(By.id("checkout-btn")).click();
} catch (NoSuchElementException e) {
    System.out.println("Checkout button missing.");
} finally {
    System.out.println("Checkout step completed.");
}

The finally block runs no matter what happens inside try or catch, useful for cleanup steps like closing a driver.

Custom Exception Messages

if (driver.findElements(By.id("error-banner")).size() > 0) {
    throw new RuntimeException("Unexpected error banner appeared on the page.");
}

This throws a custom exception with a clear message when a specific unwanted condition appears, making test reports easier to understand.

Practical Example

A test clicks a Add to Cart button that sometimes takes longer to become active. Wrapping the click inside a retry loop with a short pause handles the occasional StaleElementReferenceException without failing the entire test suite over a temporary timing issue.