This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Troubleshooting Assistance

How to get manage WebDriver problems.

It is not always obvious the root cause of errors in Selenium.

  1. The most common Selenium-related error is a result of poor synchronization. Read about Waiting Strategies. If you aren’t sure if it is a synchronization strategy you can try temporarily hard coding a large sleep where you see the issue, and you’ll know if adding an explicit wait can help.

  2. Note that many errors that get reported to the project are actually caused by issues in the underlying drivers that Selenium sends the commands to. You can rule out a driver problem by executing the command in multiple browsers.

  3. If you have questions about how to do things, check out the Support options for ways get assistance.

  4. If you think you’ve found a problem with Selenium code, go ahead and file a Bug Report on GitHub.

1 - Understanding Common Errors

How to get deal with various problems in your Selenium code.

Invalid Selector Exception

CSS and XPath Selectors are sometimes difficult to get correct.

Likely Cause

The CSS or XPath selector you are trying to use has invalid characters or an invalid query.

Possible Solutions

Run your selector through a validator service:

Or use a browser extension to get a known good value:

No Such Element Exception

The element can not be found at the exact moment you attempted to locate it.

Likely Cause

  • You are looking for the element in the wrong place (perhaps a previous action was unsuccessful).
  • You are looking for the element at the wrong time (the element has not shown up in the DOM, yet)
  • The locator has changed since you wrote the code

Possible Solutions

  • Make sure you are on the page you expect to be on, and that previous actions in your code completed correctly
  • Make sure you are using a proper Waiting Strategy
  • Update the locator with the browser’s devtools console or use a browser extension like:

Stale Element Reference Exception

An element goes stale when it was previously located, but can not be currently accessed. Elements do not get relocated automatically; the driver creates a reference ID for the element and has a particular place it expects to find it in the DOM. If it can not find the element in the current DOM, any action using that element will result in this exception.

Common Causes

This can happen when:

  • You have refreshed the page, or the DOM of the page has dynamically changed.
  • You have navigated to a different page.
  • You have switched to another window or into or out of a frame or iframe.

Common Solutions

The DOM has changed

When the page is refreshed or items on the page have moved around, there is still an element with the desired locator on the page, it is just no longer accessible by the element object being used, and the element must be relocated before it can be used again. This is often done in one of two ways:

  • Always relocate the element every time you go to use it. The likelihood of the element going stale in the microseconds between locating and using the element is small, though possible. The downside is that this is not the most efficient approach, especially when running on a remote grid.

  • Wrap the Web Element with another object that stores the locator, and caches the located Selenium element. When taking actions with this wrapped object, you can attempt to use the cached object if previously located, and if it is stale, exception can be caught, the element relocated with the stored locator, and the method re-tried. This is more efficient, but it can cause problems if the locator you’re using references a different element (and not the one you want) after the page has changed.

The Context has changed

Element objects are stored for a given context, so if you move to a different context — like a different window or a different frame or iframe — the element reference will still be valid, but will be temporarily inaccessible. In this scenario, it won’t help to relocate the element, because it doesn’t exist in the current context. To fix this, you need to make sure to switch back to the correct context before using the element.

The Page has changed

This scenario is when you haven’t just changed contexts, you have navigated to another page and have destroyed the context in which the element was located. You can’t just relocate it from the current context, and you can’t switch back to an active context where it is valid. If this is the reason for your error, you must both navigate back to the correct location and relocate it.

2 - Logging Selenium commands

Getting information about Selenium execution.

Each language adopts a distinctly different approach to logging information about the activity of the program.


Ruby uses a custom implementation of the default Logger class with some interesting additional features.

Logger output

By default, logs are sent to the console in stdout. if you want to store the logs in a file, add this to your code:

Selenium::WebDriver.logger.output = '/path/to/selenium.log'

Logger level

The basic levels for the Ruby logger are: :debug, :info, :warn, :error, :fatal

Selenium uses :info and :debug similar to “verbose” and “very verbose”, so the default is :warn.

To change the level of the logger:

Selenium::WebDriver.logger.level = :fatal


Warnings include everything we want users to be aware of by default. This is mostly used for deprecations. For various reasons, Selenium project does not follow standard Semantic Versioning practices. Our policy is to mark things as deprecated for 3 releases and then remove them. As such, Ruby logs deprecations as warnings, specifying what is changing, what needs to be used instead. It may include additional messages, and always includes an ID.

For example:

2022-12-24 16:07:09 WARN Selenium [DEPRECATION] [:jwp_caps] `Capabilities#version=` is deprecated. Use `Capabilities#browser_version=` instead.

Because these items can get annoying, we’ve provided an easy way to turn them off.

To turn off a specific warning, set the ID to ignore:


It accepts an Array to turn off multiple IDs:

Selenium::WebDriver.logger.ignore(%i[jwp_caps pause pauses])

To turn off all deprecation notices:



This is where the most useful information gets logged. Selenium logs the endpoints and payloads sent to and received from the driver or server. This is a great way to see what Selenium is actually doing under the hood, and can be used to determine if it is Selenium code or driver code that is causing a problem. (Unfortunately, we can’t blame the driver if Selenium is sending incorrect syntax).


This is less useful information where we log things about the servers and the sockets, and header information, etc. Debug mode is set if either $DEBUG is true or ENV['DEBUG'] has a value.