Selenium Exception Lookup — Causes & Fixes

The exceptions worth knowing cold

A handful of Selenium exceptions account for most flaky-test pain and most interview questions: StaleElementReferenceException, NoSuchElementException, TimeoutException, ElementClickInterceptedException and ElementNotInteractableException. For each, know the one-line cause and the fix by heart — it signals real hands-on experience faster than almost anything else.

From error message to fix

Search by the exception name or by what you were doing (“click”, “stale”, “timeout”). Each entry gives the root cause, the scenarios that trigger it, and a ready Java fix — usually an explicit wait on the right condition, a re-locate of the element, or a scroll-into-view. Copy the snippet, adapt the locator, and move on.

Selenium exceptions reference — cause, fix & interview answer

Every Selenium exception below is written out in full — name, root cause, when it fires, a Java fix you can paste, and a concise answer for interviews. Use the search tool above for a quick lookup, or read straight through.

// FIX 1: Add explicit wait
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.presenceOfElementLocated(By.id("submit")));

// FIX 2: Switch to iframe first
driver.switchTo().frame("frameName");
driver.findElement(By.id("submit")).click();
driver.switchTo().defaultContent();

// FIX: Re-find element just before use
public void clickWithRetry(By locator) {
    int attempts = 0;
    while (attempts < 3) {
        try {
            driver.findElement(locator).click();
            break;
        } catch (StaleElementReferenceException e) {
            attempts++;
        }
    }
}
// OR: Use Page Factory with @FindBy — handles re-lookup automatically

// FIX 1: Wait for element to be clickable
wait.until(ExpectedConditions.elementToBeClickable(By.id("btn")));

// FIX 2: Scroll element into view
JavascriptExecutor js = (JavascriptExecutor) driver;
js.executeScript("arguments[0].scrollIntoView(true);", element);

// FIX 3: Click via JavaScript if normal click fails
js.executeScript("arguments[0].click();", element);

// FIX 1: Increase timeout for slow environments
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(30));

// FIX 2: Use FluentWait with polling
Wait<WebDriver> fluentWait = new FluentWait<>(driver)
    .withTimeout(Duration.ofSeconds(20))
    .pollingEvery(Duration.ofMillis(500))
    .ignoring(NoSuchElementException.class);

// FIX 3: Check if it's a real bug — element may never appear

// FIX 1: Dismiss the overlay first
driver.findElement(By.id("cookie-accept")).click();

// FIX 2: Wait for overlay to disappear
wait.until(ExpectedConditions.invisibilityOfElementLocated(By.className("spinner")));

// FIX 3: JavaScript click bypasses overlay
((JavascriptExecutor) driver).executeScript("arguments[0].click();", element);

// FIX 4: Scroll past fixed header
js.executeScript("window.scrollBy(0, -100);"); // scroll up a bit

// BAD XPath — causes error:
// driver.findElement(By.xpath("//div[@class='btn primary']"))  // space in class

// GOOD — use contains():
driver.findElement(By.xpath("//div[contains(@class,'btn')]"));

// GOOD — CSS equivalent:
driver.findElement(By.cssSelector("div.btn.primary"));

// Validate XPath in browser: Ctrl+F in DevTools → paste XPath

// FIX: Wait for frame to be available then switch
wait.until(ExpectedConditions.frameToBeAvailableAndSwitchToIt(By.id("frameId")));

// FIX: Always return to default before switching frames
driver.switchTo().defaultContent(); // return to main
driver.switchTo().frame("targetFrame"); // switch to new frame

// FIX: Use index if name unknown
driver.switchTo().frame(0); // first frame on page

// FIX: Wait for alert then handle
wait.until(ExpectedConditions.alertIsPresent());
Alert alert = driver.switchTo().alert();
System.out.println(alert.getText());
alert.accept(); // OK
// alert.dismiss(); // Cancel

// FIX: Check for alert safely
try {
    Alert alert = driver.switchTo().alert();
    alert.accept();
} catch (NoAlertPresentException e) {
    // No alert — continue
}

// FIX: Ensure driver is initialised before use
if (driver == null) {
    driver = new ChromeDriver();
}

// FIX: Use ThreadLocal for parallel execution
private static ThreadLocal<WebDriver> driverThread = new ThreadLocal<>();

// FIX: Proper teardown — quit only once in @AfterSuite/@AfterMethod
@AfterMethod
public void tearDown() {
    if (driver != null) {
        driver.quit();
        driver = null;
    }
}

// FIX: Explicit wait for element to stabilise
Thread.sleep(500); // only as last resort — prefer:
wait.until(ExpectedConditions.elementToBeClickable(element));

// FIX: Actions class for complex clicks
Actions actions = new Actions(driver);
actions.moveToElement(element).click().perform();

// FIX: Check page stability before clicking
wait.until(driver -> ((JavascriptExecutor) driver)
    .executeScript("return document.readyState").equals("complete"));

// FIX: Set unexpected alert behaviour in capabilities
ChromeOptions options = new ChromeOptions();
options.setUnhandledPromptBehaviour(UnexpectedAlertBehaviour.ACCEPT);
driver = new ChromeDriver(options);

// FIX: Handle in test with try-catch
try {
    // test action
} catch (UnexpectedAlertPresentException e) {
    driver.switchTo().alert().dismiss();
    // log as defect — unexpected alert is likely a bug
}

// FIX: Scroll element into view first
((JavascriptExecutor) driver)
    .executeScript("arguments[0].scrollIntoView(true);", element);
// Then perform action

// FIX: Maximise window
driver.manage().window().maximize();

// FIX: Use Actions with offset
Actions actions = new Actions(driver);
actions.moveToElement(element, 0, 0).click().perform();

// FIX 1: Use WebDriverManager (auto-manages versions)
WebDriverManager.chromedriver().setup();
driver = new ChromeDriver();

// FIX 2: Add retry logic for flaky session start
int attempts = 0;
while (attempts < 3) {
    try {
        driver = new ChromeDriver();
        break;
    } catch (WebDriverException e) {
        attempts++;
        Thread.sleep(2000);
    }
}

// FIX: Check element state before action
WebElement el = driver.findElement(By.id("input"));
if (el.isEnabled() && !el.getAttribute("readonly").equals("true")) {
    el.clear();
    el.sendKeys("test data");
}

// FIX: For disabled fields — use JavaScript
((JavascriptExecutor) driver)
    .executeScript("arguments[0].removeAttribute('disabled');", el);
// Note: Removing disabled is for testing purposes only

// Same fixes as NoSuchElementException
// Selenium 4 unifies these under NotFoundException
wait.until(ExpectedConditions.presenceOfElementLocated(locator));

// FIX: Increase script timeout
driver.manage().timeouts().scriptTimeout(Duration.ofSeconds(30));

// FIX: For async scripts, ensure callback is called
((JavascriptExecutor) driver).executeAsyncScript(
    "var callback = arguments[arguments.length - 1];" +
    "setTimeout(function(){ callback('done'); }, 2000);");

// FIX: Add retry at test level
@Test(retryAnalyzer = RetryAnalyzer.class)
public void myTest() { ... }

// RetryAnalyzer:
public class RetryAnalyzer implements IRetryAnalyzer {
    int count = 0;
    public boolean retry(ITestResult result) {
        return count++ < 2; // retry 2 times
    }
}

// FIX: Ensure session keepalive for cloud grids
// Check provider docs for timeout settings

// Selenium 4 — use ElementNotInteractableException handling
wait.until(ExpectedConditions.visibilityOfElementLocated(locator));

// Check visibility in test:
boolean isVisible = element.isDisplayed();

// JS to check:
Boolean visible = (Boolean) ((JavascriptExecutor) driver)
    .executeScript("return arguments[0].offsetWidth > 0 " +
                   "&& arguments[0].offsetHeight > 0;", element);

// FIX: Wrap JS in try-catch with error handling
try {
    Object result = ((JavascriptExecutor) driver)
        .executeScript("return document.getElementById('btn').click();");
} catch (JavascriptException e) {
    System.out.println("JS Error: " + e.getMessage());
    // Fall back to Selenium click
    driver.findElement(By.id("btn")).click();
}

// FIX: Always initialise driver before test
@BeforeMethod
public void setUp() {
    driver = new ChromeDriver(); // or ThreadLocal
}

// FIX: Null-safe check
if (driver != null) {
    driver.findElement(By.id("test"));
}

// FIX: ThreadLocal pattern
private static ThreadLocal<WebDriver> tlDriver = new ThreadLocal<>();
public static WebDriver getDriver() {
    return tlDriver.get();
}

How to use this tool

1. Type an exception name or a symptom like “stale” or “timeout”.
2. Expand the match to see root cause and when it happens.
3. Copy the Java fix and adapt the locator to your page.
4. Read the interview answer to explain it crisply in a panel.

Frequently asked questions

Related guides & tools