Most advice on StaleElementReferenceException comes from Selenium and talks about a page DOM that was reloaded. In a native Appium session there is no page. The element reference your test holds is an id in an element cache on the device: in the UiAutomator2 server on Android, and in WebDriverAgent (WDA) on iOS. Whether the reference is stale is decided there, and each driver tells you why in the error message.
This article covers only what is specific to mobile: how the two caches work, what each message means, and which app behaviors cause it.
Short answer: read the message text, not just the exception class. On Android, the UiAutomator2 server already tries to find a stale element again with your original locator. When that cannot work, the message says why: the element came from a findElements list, the screen was rebuilt (for example by a rotation), or nothing matches anymore. On iOS, WDA's message says the element "is not present in the current view anymore", and it points to the boundElementsByIndex setting when the cause is an identity binding error. In both cases the lasting fix is to keep locators, not elements, and find again after anything that rebuilds the screen.
Where a mobile element reference lives
When your client calls findElement, the driver asks a server on the device to find the element. That server stores the result in a cache and returns an id. Every later command (click, getText) sends the id back, and the server looks it up.
- Android, UiAutomator2: the server keeps an LRU cache of up to 500 elements per session (
MAX_CACHE_SIZE = 500in the server source). The id is built from the accessibility node's window id and source node id. So the id identifies one view on screen, not your locator. - iOS, XCUITest: WDA keeps an LRU cache of up to 1024 elements (
ELEMENT_CACHE_SIZE = 1024). - Web views: in a web context, commands do not go to these servers at all. More on that below.
A reference goes stale when the server can no longer connect the cached id to something on screen.
Android (UiAutomator2)
The server tries to restore stale elements first
When a cached element no longer responds, the UiAutomator2 server does not fail right away. It logs "has been reported as stale … Trying to restore it" and runs your original locator again. If that finds the same view, the command continues and your test never sees an error.
Restoring only works when all of these are true:
- The element came from
findElement(a single match), not fromfindElements. - It was found by
id,accessibility id,class name,xpathor-android uiautomator. - The locator finds a view, and that view has the same id as before. In other words, it is the same view, not a new one that looks the same.
When any of these fails, you get a stale element reference error. The message (quoted from the server source) tells you which case you hit:
Cached elements '<locator>' do not exist in DOM anymore: the element came from afindElementslist. List results are never restored, because the locator matches many views.The element '<locator>' is not linked to the same object in DOM anymore: the locator still finds something, but it is a different view. The screen was rebuilt.The element '<locator>' does not exist in DOM anymore: the locator finds nothing now. If the element was cached without a locator, the same message shows the element id instead.
These three are what you get when the restore fails. A stale error can also come in the middle of a command. If the view disappears after the server checked it but before the action ran, the server reports UiAutomator's own stale-object error as stale element reference. Some commands report it with the generic text The referenced element is no longer attached to the DOM. The fix is the same as for the rebuilt-screen case: find the element again and retry the step.
A fourth message looks similar but is a different error: The element identified by '<id>' is not present in the cache or has expired. Try to find it again. The server returns it as no such element, not as a stale reference. It means the id is not in the cache at all, for example because more than 500 newer elements pushed it out.
Cause 1: you loop over a list and scroll
This is the most common Android case. You call findElements on the rows of a list, then scroll, then use the stored rows. The first message in the table appears, because list results cannot be restored.
There is a second problem that shows no error at all. Android's RecyclerView documentation says the list "reuses the view for new items that have scrolled onscreen". The Appium id identifies a view, not the data in it. So after a scroll, a stored row reference can point at a view that now shows a different item.
The fix is to never keep row references across a scroll. Find rows by their content each time:
from appium.webdriver.common.appiumby import AppiumBy
def tap_row(driver, title, max_scrolls=10):
# Assumes the title contains no double quote (it would break the XPath).
row = f'//android.widget.TextView[@text="{title}"]'
can_scroll = True
for _ in range(max_scrolls + 1):
matches = driver.find_elements(AppiumBy.XPATH, row)
if matches:
matches[0].click() # use it right away, before anything else changes
return
if not can_scroll:
break
lst = driver.find_element(AppiumBy.ID, "com.example:id/list")
can_scroll = driver.execute_script(
"mobile: scrollGesture",
{"elementId": lst.id, "direction": "down", "percent": 0.75},
)
raise AssertionError(f"row not found: {title}")
mobile: scrollGesture returns true while more scrolling is possible. When it returns false, that last scroll has still run, so the loop checks the rows once more and then stops. Note that the list container is also found again on each pass.
Cause 2: a configuration change rebuilt the screen
Android's documentation is direct about this: "The system recreates an Activity when a configuration change occurs." It destroys the old Activity instance and creates a new one, and "the system also recreates the UI with the new configuration". Rotation is the usual example. A language change also does it.
Unless the app declares that it handles the change itself, every view on that screen is new after this. Your locator still matches, but it finds a different view, so you get is not linked to the same object in DOM anymore. If your test rotates the device, changes the locale or switches dark mode, find every element again after the change.
The same applies to anything else that rebuilds the screen: going back to a screen that was recreated, or restarting the app.
Cause 3: the accessibility cache is out of date
The UiAutomator2 driver works through Android's accessibility layer, which has its own cache. The driver docs say it "automatically resets this cache before any element lookup, as well as before retrieving the page source". For apps with "highly dynamic elements", they suggest calling it yourself "in order to avoid stale reference errors or interaction issues":
driver.execute_script("mobile: resetAccessibilityCache")
The docs add that this call "also waits until the app under test becomes idle", so calling it after every step can slow the run down. It is available from driver version 6.4.1.
If you turned on the deferAccessibilityCacheReset setting (driver 8.1.0 and later), know what it changes. By default the cache is cleared for every lookup, which "prevents the cache from going stale". With the setting on, the server only clears it after it sees a relevant UI-change event. That saves memory under many lookups, but it gives up some of that protection. Turn it off again while you debug stale errors.
The driver's multi-window guide gives the same advice for apps with several windows: reset the accessibility cache "if encountering stale element references after window changes".
iOS (XCUITest / WebDriverAgent)
Read the WDA message
WDA has two stale messages:
The element identified by "<id>" is either not present or it has expired from the internal cache. Try to find it again: the id is not in the cache. Unlike Android, iOS reports this as a stale element reference. The cache holds 1024 elements, so a test that keeps references while making many other lookups can lose old ones.The previously found element "<element>" is not present in the current view anymore. Make sure the application UI has the expected state: the element is in the cache, but WDA could not find it on screen. The screen changed: navigation, a closed alert or sheet, or a restarted app.
If the original XCTest error contains "Identity Binding", WDA adds a hint to the second message: "You could also try to switch the binding strategy using the 'boundElementsByIndex' setting for the element lookup".
Cause 1: the element binding
XCTest can connect a found element to what is on screen in two ways. By default, the driver uses allElementsBoundByAccessibilityElement. The boundElementsByIndex setting switches lookups to allElementsBoundByIndex. Try it when the hint above appears:
driver.update_settings({"boundElementsByIndex": True})
The setting is false by default. Change it for the screens that need it and check that your other lookups still behave as expected.
Cause 2: an element property changed
Sometimes the screen did not change, but the element did: its label or value was updated. The XCUITest driver has a capability for this case. The docs describe appium:useNativeCachingStrategy like this: "Set this capability to false in order to use the custom elements caching strategy. This might help to avoid stale element exception on property change." By default (true), the native XCTest cache is used for all locators except XPath.
{
"appium:useNativeCachingStrategy": false
}
This is a capability, so it applies to the whole session. Set it when a test reads an element, the app updates that element, and the next read fails as stale.
Cause 3: actions while the screen is still changing
WDA waits before acting. waitForIdleTimeout (default 10 seconds) waits for the app's main thread to be idle. animationCoolOffTimeout (default 2 seconds) waits for animations to end after actions such as a click. Both can be set to 0 to turn the check off. The docs mark this as "not recommended" for waitForIdleTimeout.
If a suite turned these off to run faster, it can find elements in the middle of a transition. Elements found during a transition can be the ones that are about to be replaced. If you see stale errors right after taps and you changed these settings, restore the defaults first.
Hybrid apps: an element belongs to its context
In a hybrid app, switching between NATIVE_APP and a WEBVIEW_* context changes which component handles your commands. The UiAutomator2 docs put it plainly: in the native context the driver forwards commands to the UiAutomator2 server app, and in a web view context it forwards them to an instance of ChromeDriver. On iOS, the docs say that after switching to a web view, findElement "will operate on the DOM of the web view, rather than return native elements".
So an element found in one context is held by a different component than the one that serves the other context. Do not carry element references across switch_to.context(...). Find them again in the context you are in.
Checklist
- Read the message text. On Android, it tells you whether the element came from a list, was rebuilt, or is gone.
- Keep locators in page objects, not elements. Find the element right before you use it.
- Never keep
findElementsresults across a scroll. Lists reuse their row views. - Find everything again after rotation, locale or theme changes, back navigation and app restarts.
- Android: call
mobile: resetAccessibilityCachefor very dynamic screens, and check thatdeferAccessibilityCacheResetis off while debugging. - iOS: try
boundElementsByIndexwhen the message mentions "Identity Binding", andappium:useNativeCachingStrategy: falsewhen the element's properties change. - iOS: keep the default
waitForIdleTimeoutandanimationCoolOffTimeoutunless you have a reason to change them. - Hybrid apps: find elements again after every context switch.
Sources
Checked on 2026-10-28 against the official documentation and source of Appium UiAutomator2 driver 8.7.3, XCUITest driver 12.22.2, the UiAutomator2 server and WebDriverAgent (current main of the appium-android and appium-ios repositories), and the Android developer documentation:
- UiAutomator2 server element cache and restore logic:
ElementsCache.java,Session.java(cache size),AxNodeInfoHelper.java(element id),SafeRequestHandler.javaandAxNodeInfoExtractor.java(stale errors during a command) - UiAutomator2 driver: execute methods (
mobile: resetAccessibilityCache,mobile: scrollGesture), settings (deferAccessibilityCacheReset), multi-window guide, hybrid apps - WebDriverAgent element cache and stale errors:
FBElementCache.m,XCUIElement+FBUtilities.m - XCUITest driver: settings (
boundElementsByIndex,waitForIdleTimeout,animationCoolOffTimeout), capabilities (appium:useNativeCachingStrategy), hybrid apps - Android: Create dynamic lists with RecyclerView, Handle configuration changes