Skip to main content

Handling StaleElementReferenceException

A StaleElementReferenceException occurs when an element that was previously located on the page is no longer attached to the DOM. This typically happens when:

  • the page is refreshed
  • a dynamic element is removed or replaced
  • the page re-renders or its state changes after the initial lookup

How Kolibrium handles stale elements (no manual retries needed)​

Kolibrium’s locator delegates are resilient by default. When a StaleElementReferenceException happens during lookup or readiness checks, Kolibrium simply tries again on the next poll of its FluentWait:

  • Single-element delegates cache by default. On a stale reference, the cached element is cleared and a fresh lookup is performed on the next poll.
  • Multi-element delegates are never cached. On a stale reference, the next poll takes a fresh snapshot of the elements.
note

You don’t need to add StaleElementReferenceException to the ignored exception list in your WaitConfig. It’s handled internally during polling. Kolibrium also ignores NoSuchElementException automatically. See “Configuring waiting behavior” for details.

See Configuring waiting behavior for details.

Default readiness conditions​

Unless you override readyWhen:

  • Single element: the element must be displayed
  • Multiple elements: the collection must be non-empty and all elements displayed

You can customize readyWhen per delegate, or set site-wide defaults through your site context configuration if you use it.

Logging​

By default, locator delegates do not emit a warning when a stale reference is encountered; the retry is silent.

If you want visibility during troubleshooting, enable the lightweight LoggerDecorator which logs at trace/debug levels:

DecoratorManager.addDecorators(LoggerDecorator())

With debug logging enabled for dev.kolibrium, you may see messages such as:

stale element reference while reading element’s HTML tag; element reference is no longer valid

Practical tips​

  • Prefer accessing the delegate when you need it instead of storing WebElement references for a long time.
  • For highly dynamic pages, consider disabling caching for single elements to always re-locate on access, for example: id("submit", cacheLookup = false).