A Selenium @CacheLookup page-object field throws StaleElementReferenceException on every call after a re-render — why does it never recover?

## What the annotation actually switches on `@CacheLookup` is a **marker annotation** — `@Retention(RUNTIME)`, `@Target(FIELD)`, no members at all. Its own Javadoc describes what it asserts: that the element "never changes (that is, that the same instance in the DOM will always be used)". `Annotations.isLookupCached()` simply reports whether the field carries it, and the `DefaultElementLocator` constructor copies that answer into a `shouldCache` flag when `PageFactory.initElements` decorates the field. Nothing revisits the decision afterwards. ## The cache is one field, written once In Selenium 4 the whole caching mechanism is a handful of lines inside `DefaultElementLocator.findElement()`: ```java if (cachedElement != null && shouldCache()) { return cachedElement; } WebElement element = searchContext.findElement(by); if (shouldCache()) { cachedElement = element; } return element; ``` The first call on the field performs a real `findElement` and stores the returned `WebElement` in a private `cachedElement`. Every later call returns that stored instance without touching the browser. There is **no** branch anywhere that clears it: no `reset()`, no expiry, no staleness probe, and nothing in `LocatingElementHandler` inspects the exception that comes back from a call in order to invalidate anything. ## Why the failure becomes permanent A re-render detaches the node the stored handle points at. *Why* a detached node makes a handle stale is the driver's element-identity story rather than the page factory's; what the page factory adds is that the stale handle is now **permanent**. On a laundry pickup scheduler the sequence is mundane: 1. `pickupWindow.getText()` runs a real `findElement`; the element is stored in `cachedElement`. 2. The customer picks a different pickup date and the scheduler redraws its slot panel, detaching the old node. 3. The next `pickupWindow.click()` returns the stored handle and the command fails with `StaleElementReferenceException`. 4. Call four, call five and every retry return the same stored handle and fail identically. An uncached field would have recovered at step 3 on its own, because `searchContext.findElement(by)` would have run again and found the redrawn node. The annotation is the entire difference between a suite that shrugs off a redraw and one that dies at it, and because the failure is identical on every attempt, it is easy to misread as a locator problem rather than a caching one. ## Neither locator factory rescues a cached field | Field | Behaviour on call N greater than 1 | Recovers from a re-render? | |---|---|---| | `@FindBy` alone | runs `searchContext.findElement(by)` again | yes — a fresh element every call | | `@FindBy` plus `@CacheLookup` | returns the stored `cachedElement` | no — the same detached handle forever | | `@CacheLookup` under `AjaxElementLocatorFactory` | polls, but each poll delegates to the cache | no — polling cannot help | That third row is the one that surprises people. `AjaxElementLocator` overrides `findElement` to poll for a while instead of failing instantly, but each poll calls `DefaultElementLocator.findElement`, which short-circuits on `cachedElement`. Its `isElementUsable` hook returns `true` by default, so a detached element is happily accepted as usable and the poll succeeds immediately with the wrong answer. ## What actually clears the cache Only building a new locator does, and the only supported way to build one is another `PageFactory.initElements` — in practice, a new page object. - Assigning `null` to the field does nothing useful: `initElements` put a proxy there, and the cache lives in the locator behind the proxy, not in the field. - Navigating, refreshing or sleeping does nothing: no code path in Selenium touches `cachedElement`. - Catching the exception and repeating the same call does nothing: the repeat hits the same cache and throws again. - Swapping to `AjaxElementLocatorFactory` does nothing, for the reason in the table above. ## When the annotation is defensible - Use it only for what the Javadoc actually claims: a node created once and never replaced for the life of the page — the scheduler's static header, or the `<form>` element that wraps the booking fields. - Treat it as a liability on anything the application redraws: slot rows, availability lists, anything rendered after a background request completes, anything a component framework owns. - Weigh the saving honestly. It removes one `findElement` round trip per method call, which is small beside the cost of a suite that fails permanently after a redraw. - The uncached default — re-query on every method call — is precisely the behaviour that makes the proxy model tolerable, so removing the annotation is usually the whole fix and it is one line per field.