Skip to content
Selenium WebDriver reference

Selenium WebDriver exceptions, explained one by one

14documented messages
6categories

Last verified

Selenium reports failures as exceptions whose class name you will recognize from the stack trace: NoSuchElementException, StaleElementReferenceException, TimeoutException and so on. In Python they live in selenium.common.exceptions; in Java in org.openqa.selenium. The class names are nearly identical across languages because they map to the error codes defined by the W3C WebDriver standard, such as no such element and stale element reference.

The text after Message: comes from the browser driver (ChromeDriver, GeckoDriver, msedgedriver, SafariDriver), not from Selenium itself. That is why the same exception can carry different wording in Chrome and Firefox, and why the wording changes between driver versions. Search for the exception class plus the key phrase in the message. Two other parts of a Selenium error help: the Session info line shows the browser version actually used, and the stack trace shows which line of your code sent the failing command. Recent Python releases also append a link to the matching section of Selenium's error documentation.

The exceptions below fall into a few families: locating elements, interacting with them, waits, windows, alerts and sessions, and driver or browser start-up problems such as ChromeDriver version mismatches. Each entry quotes a literal message, explains what it does and does not mean, and lists fixes in the order worth trying. Code examples use the current Selenium 4 Python API. For how Selenium compares with Playwright and Puppeteer, see Playwright vs Selenium vs Puppeteer.

Official reference: Selenium docs - Understanding Common Errors

How to read a Selenium error

A Selenium exception has three useful parts: the exception class, the driver's message, and the stack trace showing your line of code.

Traceback (most recent call last):
  File "scrape.py", line 18, in <module>
    driver.find_element(By.CSS_SELECTOR, "#login").click()
selenium.common.exceptions.NoSuchElementException: Message: no such element: Unable to locate element: {"method":"css selector","selector":"#login"}
  (Session info: chrome=131.0.6778.86)

All 14 messages

Jump to: Locating elements (2) · Stale elements (1) · Clicking & interacting (3) · Waits & timeouts (1) · Windows, alerts & sessions (3) · Drivers & browser start-up (4)

Locating elements

MessageHTTPType
NoSuchElementException: Unable to locate elementselenium.common.exceptions.NoSuchElementException: Message: no such element: Unable to locate element: {"method":"css…—Retryable
InvalidSelectorException: invalid selectorselenium.common.exceptions.InvalidSelectorException: Message: invalid selector: An invalid or illegal selector was specified; For…—Permanent - do not retry

Stale elements

MessageHTTPType
StaleElementReferenceException: stale element referenceselenium.common.exceptions.StaleElementReferenceException: Message: stale element reference: stale element not found in the current frame;…—Retryable

Clicking & interacting

MessageHTTPType
ElementClickInterceptedException: element click interceptedselenium.common.exceptions.ElementClickInterceptedException: Message: element click intercepted: Element <button id="submit">...</button>…—Retryable
ElementNotInteractableException: element not interactableselenium.common.exceptions.ElementNotInteractableException: Message: element not interactable; For documentation on this error, please…—Permanent - do not retry
MoveTargetOutOfBoundsException: move target out of boundsselenium.common.exceptions.MoveTargetOutOfBoundsException: Message: move target out of bounds—Permanent - do not retry

Waits & timeouts

MessageHTTPType
TimeoutException (WebDriverWait timed out)selenium.common.exceptions.TimeoutException: Message: (Java) org.openqa.selenium.TimeoutException: Expected condition failed: waiting…—Retryable

Windows, alerts & sessions

MessageHTTPType
NoSuchWindowException: target window already closedselenium.common.exceptions.NoSuchWindowException: Message: no such window: target window already closed from unknown error: web view not…—Permanent - do not retry
InvalidSessionIdException: invalid session idselenium.common.exceptions.InvalidSessionIdException: Message: invalid session id; For documentation on this error, please visit:…—Permanent - do not retry
UnexpectedAlertPresentException: unexpected alert openselenium.common.exceptions.UnexpectedAlertPresentException: Alert Text: Are you sure you want to leave? Message: unexpected alert open:…—Retryable

Drivers & browser start-up

MessageHTTPType
This version of ChromeDriver only supports Chrome version Nselenium.common.exceptions.SessionNotCreatedException: Message: session not created: This version of ChromeDriver only supports Chrome…—Configuration
Chrome failed to start: DevToolsActivePort file doesn't existselenium.common.exceptions.SessionNotCreatedException: Message: session not created: Chrome failed to start: exited abnormally. (unknown…—Configuration
WebDriverException: unknown error: cannot find Chrome binaryselenium.common.exceptions.WebDriverException: Message: unknown error: cannot find Chrome binary—Configuration
NoSuchDriverException: Unable to obtain driver for chromeselenium.common.exceptions.NoSuchDriverException: Message: Unable to obtain driver for chrome; For documentation on this error, please…—Configuration

Definitions

Selenium guides, limits and tools

Other error directories

Frequently asked questions

What is the difference between implicit and explicit waits?

An implicit wait makes every find_element call poll for up to a set time before raising NoSuchElementException. An explicit wait (WebDriverWait with an expected condition) waits for one specific condition, such as visibility or clickability. Explicit waits are more precise. Selenium's documentation warns against mixing both, because the combination can produce unpredictable wait times.

Do I still need to download ChromeDriver manually?

Usually not. Since Selenium 4.6, Selenium Manager is bundled with the bindings and automatically detects your browser version, then downloads the matching driver, and can even download the browser. Manual drivers are still useful in offline or locked-down environments, but a stale manual driver on PATH is the most common cause of version mismatch errors.

Why does the same exception have different messages?

The exception class comes from Selenium and maps to a W3C WebDriver error code, but the message text comes from the browser driver. ChromeDriver, GeckoDriver and SafariDriver word the same condition differently, and ChromeDriver has changed wording between versions. Search for the exception class together with the key phrase from the message.

Is a JavaScript click a good fix for click errors?

Only sometimes. driver.execute_script('arguments[0].click()', el) bypasses the checks that produce ElementClickInterceptedException and ElementNotInteractableException, so it can click elements a real user could not reach. That may hide a real bug, such as a modal blocking the page. Use it after confirming the obstruction is cosmetic, and prefer waiting or dismissing overlays.

What does the Session info line in a Selenium error mean?

It shows the browser and version that the session actually used, for example chrome=131.0.6778.86. Compare it with your ChromeDriver version and with what you expect to be installed. It is the quickest way to spot that a different browser binary, or an older one, was launched than the one you intended.

How do I make Selenium errors easier to debug in CI?

Take a screenshot and save driver.page_source in an exception handler, log driver.current_url, pass descriptive messages to WebDriverWait.until(), and set an explicit window size so headless runs match local ones. Enabling driver logging also records start-up problems such as crashes, missing binaries and version mismatches.

Which locator strategy is most reliable?

Stable, purpose-built attributes such as id, name or a data-testid attribute, located with By.ID, By.NAME or a short CSS selector. Long XPath expressions and generated class names break whenever markup changes. Use XPath when you need to match visible text or navigate to a parent or sibling, which CSS cannot do.

Why does my script work locally but fail headless on a server?

Headless servers differ in window size, available fonts, shared memory, user permissions and sometimes browser version. Small default windows trigger mobile layouts that hide elements, and containers can crash Chrome on start. Set --window-size, use --headless=new, add --disable-dev-shm-usage in Docker, and log browser versions from both environments.

Run browser automation you can watch and take over

Autonoly runs each job in a real cloud Chromium browser driven by Playwright. Timeouts and detached elements still happen; the difference is that you can watch the run live, see the step that failed, and take control of the browser to finish it.