Blog
Selenium NotFoundException: Causes, Fixes & Solutions

Rishabh Kumar
Published on

Table of contents
Lorem ipsum
Lorem ipsum
Lorem ipsum
Lorem ipsum
Lorem ipsum
NotFoundException is one of the most common and frustrating errors in Selenium WebDriver. It stops a test as soon as the driver can’t locate an element on the page. For teams running hundreds or thousands of automated tests, a single locator failure can cascade into hours of debugging, false failures and delayed releases.
This guide covers what NotFoundException is, what causes it, how to fix each cause with working Java examples, and why AI-native platforms approach element identification differently.
What is NotFoundException in Selenium?
NotFoundException is a parent exception class in Selenium WebDriver, thrown when WebDriver can’t find what a command is looking for. It sits in the org.openqa.selenium package and is the base class for several more specific exceptions.
Exception | When It’s Thrown |
|---|---|
| |
NoSuchFrameException | The test tries to switch to a frame or iframe that doesn’t exist |
NoSuchShadowRootException | Selenium 4 tries to get a shadow root from an element that doesn’t have one |
In practice, NoSuchElementException accounts for the vast majority of NotFoundException errors. When your script calls driver.findElement(By.id("submit-button")) and no element with that ID exists in the DOM at that moment, WebDriver throws it and the test fails.
The stack trace typically looks like this:
ChromeDriver reports By.id lookups as CSS selectors, which is why the trace shows #submit-button. Understanding why this happens, and how to prevent it, is fundamental to building stable Selenium test suites.
Common Causes of NotFoundException in Selenium
Cause | What Happens | Typical Fix |
|---|---|---|
Incorrect or outdated locators | The locator no longer matches any element | More resilient locators and centralised page objects |
Timing and synchronisation | Selenium looks before the element is rendered | Explicit waits |
Frames and shadow DOM | The element is in a separate document context | Switch frames, or access the shadow root |
Dynamic attributes | IDs or classes change on every page load | Locators based on stable attributes |
Navigation and state changes | The test looks for an element on a page it has already left | Wait for the right page state before acting |
Hidden elements removed from the DOM | The framework deletes the element when it’s hidden | Wait for the state that shows it |
Incorrect or Outdated Locators
The most straightforward cause is a locator that simply doesn’t match any element on the page. This happens when element IDs, class names or attributes change during development. A button that was id="login-btn" last sprint might become id="auth-submit-btn" after a UI refactor, and Selenium has no way of knowing those two locators refer to the same button. In large suites, fixing broken locators is one of the biggest sources of maintenance work.
Timing and Synchronization Issues
Modern web applications load content asynchronously. Frameworks such as React, Angular and Vue render elements after the initial page load. If Selenium looks for an element before the framework has rendered it, the element genuinely doesn’t exist in the DOM yet.
This is the second most common cause of NotFoundException. The page can look complete to a person while the DOM is still being built underneath.
Elements Inside Frames or Shadow DOM
Elements inside iframes or shadow DOM exist in separate document contexts. Selenium can’t see elements inside a frame until you switch to that frame with driver.switchTo().frame(), and shadow DOM hides elements from standard locators.
Enterprise applications such as Salesforce Lightning, Microsoft Dynamics 365 and ServiceNow use iframes and shadow DOM extensively, which makes NotFoundException especially common when automating them.
Dynamic Element Attributes
Single-page applications and low-code platforms often generate element attributes at runtime. An element might have id="field_abc123" on one page load and id="field_xyz789" on the next. Any locator that depends on these values will fail intermittently, producing errors that are hard to reproduce.
Page Navigation and State Changes
If a test tries to interact with an element on page A after the browser has already moved to page B, the element no longer exists in the current DOM. This is common in multi-step workflows where navigation happens between actions.
6. Invisible or Hidden Elements
Elements styled with display:none or visibility:hidden still exist in the DOM but can’t be interacted with. findElement() can locate them, but some frameworks remove elements from the DOM entirely when hiding them, which triggers NotFoundException.
How to Fix NotFoundException in Selenium
Use Explicit Waits Instead of Implicit Waits
The most effective fix for timing-related NotFoundException errors is an explicit wait, using WebDriverWait with ExpectedConditions.
Explicit waits check the DOM repeatedly until the element appears or the timeout expires, which handles asynchronous rendering without adding unnecessary delays.
Two things to avoid:
Thread.sleep(): hard-coded pauses slow tests down when elements load quickly and still fail when they load slowly.Mixing implicit and explicit waits: the Selenium documentation warns that combining them can cause unpredictable wait times, so choose explicit waits and keep the implicit wait at zero.
Build Resilient Locator Strategies
Locator Type | Strengths | Watch Out For |
|---|---|---|
ID | Fast and reliable when IDs are stable and unique | Long chains tied to page structure |
CSS selector | Good balance of speed, readability and flexibility | Long chains tied to page structure |
Relative XPath | Powerful for complex cases, such as | Absolute paths that depend on exact DOM structure |
Name, class name or tag name | Simple for unique elements | Many elements sharing the same class or tag |
When attributes are dynamic, build locators around stable characteristics: element type, visible text, ARIA labels, or data-* attributes that developers add on purpose for testing.
Handle Frames and Shadow DOM Correctly
For elements inside iframes, always switch to the correct frame before locating elements:
For shadow DOM elements, use JavaScript to reach inside the shadow boundary:
Selenium 4 also offers a native option for open shadow roots:
getShadowRoot() only supports CSS selectors inside the shadow root, not XPath. For nested shadow roots, repeat the step for each layer.
Implement the Page Object Model
The Page Object Model (POM) keeps the locators for each page in one class. When an element changes, you update the locator once instead of searching through dozens of test scripts.
POM reduces the effort of fixing NotFoundException, but it doesn’t prevent it. Locators still break when the application changes.
Add Retry Logic for Flaky Elements
For elements that fail intermittently because of timing or rendering race conditions, a retry can improve stability:
Use this sparingly. Retries mask the underlying problem, add execution time, and can hide real defects when an element genuinely shouldn’t appear. Explicit waits should remain the main fix.
Why NotFoundException is a Symptom of a Deeper Problem
Every fix above is a workaround:
Explicit waits compensate for Selenium not understanding page state.
Resilient locators compensate for Selenium identifying elements by technical attributes rather than what they’re for.
Page Object Models compensate for locator maintenance growing with every page and test.
The underlying limitation is architectural. Selenium identifies each element with a single locator. When that locator stops matching, the test fails, and no amount of clever XPath or CSS changes that.
For teams maintaining a few dozen tests, these workarounds are manageable. For enterprises running thousands of tests across SAP, Salesforce, Oracle Cloud and Dynamics 365, locator maintenance can take more time than writing new tests.
To follow how teams move from locator-based scripts to tests that keep pace with application changes, read our guide to self-healing in continuous testing.
How AI Native Platforms Eliminate NotFoundException
AI-native platforms identify elements differently. Instead of relying on one locator, they build a fuller picture of each element from many signals in the page.
Element Identification from Many Signals
Virtuoso QA identifies each element from many attributes at once, including its visible text, position, surrounding context, ARIA attributes and structure. If a button’s ID changes from submit-btn to order-confirm, Virtuoso QA can still find it from its other characteristics.
Repairs You Can Review
When the application changes and an element can’t be found the usual way, Virtuoso QA proposes a repair, and your team accepts or rejects it. Tests keep running through UI changes, and every change to a test leaves a record, so a passing run never hides an edit nobody agreed to.
Consider a 500-test regression suite running against a Salesforce Lightning application that receives three major releases a year. With Selenium, each release can break many locators, all needing manual investigation. With reviewable repairs, the team works through a list of proposed fixes instead of debugging stack traces one by one.
Natural Language Instead of Locators
Tests are written in plain English, so there’s no locator for you to write or maintain. Instead of writing:
testers write:
The platform matches each plain English instruction to the right element on the page.
To learn how plain English steps let more of the team build and maintain tests, read our guide to natural language programming in testing.
Live Authoring Shows Problems as You Write
Live Authoring runs each step as it’s written, so you see straight away whether the element was found and the action worked. That removes the slow cycle of writing, running, debugging and repeating.
When a step fails, the tester sees what happened in real time and adjusts it there and then, with no stack trace to parse and no CI screenshot to interpret.
Clear Answers When Tests Fail
When a run fails, Virtuoso QA shows the failed step beside the same step from the last passing run, with screenshots, the DOM snapshot, network data and a likely cause. Instead of reading “Unable to locate element”, the team sees what changed on the page.
Moving Existing Selenium Suites
Virtuoso QA's GENerator converts existing Selenium tests into plain English journeys, so teams keep the coverage they’ve built while leaving locator maintenance behind.
When to Use Selenium Fixes vs AI-Native Testing
Situation | Best Approach |
|---|---|
A small team with a stable application and a modest suite | Selenium with explicit waits, resilient locators and page objects |
Engineers own the code and the tests, and have time to maintain the framework | Selenium or another code-based framework |
Hundreds or thousands of tests across dynamic enterprise platforms | An AI-native platform with reviewable repairs |
Frequent vendor releases, such as Salesforce or Dynamics 365 | An AI-native platform with reviewable repairs |
Business analysts and manual testers need to contribute | Plain English authoring |
The decision isn’t about whether Selenium is a good tool. It’s about whether locator-based automation can scale to your testing demands without taking up a disproportionate share of your team’s time.
Related Reads
ElementNotInteractableException in Selenium: Complete Fix Guide
From Selenium Scripts to Self-Healing Tests: The Complete Journey of Test Automation
Selenium Timeouts Explained: Implicit, Explicit, Fluent Waits
Dynamic XPath in Selenium Explained With Practical Examples
Selenium ChromeDriver Setup Guide: Install, Configure & Run Chrome Tests
Frequently Asked Questions
What’s the difference between NotFoundException and NoSuchElementException?
How do I fix NoSuchElementException in Selenium?
Should I use implicit or explicit waits?
How do I find elements inside shadow DOM in Selenium?
Can AI-native testing remove NotFoundException completely?
Written by

Rishabh Kumar
AI Testing & Quality Engineering Contributor
Rishabh leads business development and marketing at Virtuoso QA. He writes about AI-powered test automation, end-to-end testing, self-healing tests, and quality engineering, exploring how these capabilities can improve test coverage, reduce test maintenance, and support reliable software releases.











