Why Is Playwright Timing Out? – Causes and Fixes
Learn why Playwright times out: wrong selectors, frames, navigation waits, actionability checks, and slow pages — with a fix for each.
A Playwright timeout means a condition never became true within the limit. The library waits for elements to be actionable, so a timeout is usually a statement about the page rather than about speed.
1. Read the Error First
Playwright's timeout messages name what it was waiting for — which selector, which state, and how long. That text is the diagnosis:
Timeout 30000ms exceeded.
waiting for locator('button.submit') to be visible
"To be visible" is different from "not found", and both are different from a navigation timeout.
2. The Element Is Not There
The most common cause is a selector that no longer matches.
- Generated class names changed on the last deploy.
- The element is inside an iframe, so a page-level query cannot see it.
- It is inside a shadow root that ordinary selectors do not pierce.
- The page rendered a different variant — logged out, another locale, an A/B branch.
Verify by pausing and querying interactively, or by dumping the page content and searching it for the expected text.
3. The Element Exists but Is Not Actionable
Playwright waits for an element to be attached, visible, stable, and enabled before acting. A timeout can therefore occur with the element present:
| State | Typical reason |
|---|---|
| Not visible | Zero size, display: none, or off-screen |
| Not stable | Still animating or moving |
| Not enabled | Disabled until a form validates |
| Obscured | A cookie banner or modal covers it |
The obscured case is the most common in practice, and the fix is to dismiss the overlay first.
4. Navigation Timeouts
goto waits for a load state. Choosing the wrong one causes timeouts on pages that never reach it:
domcontentloaded— the document parsed; fastest and usually sufficient.load— all subresources finished; can hang on pages with long-polling or streaming assets.networkidle— no network activity for a period; unreliable on pages with persistent connections.
Prefer domcontentloaded, then wait explicitly on the element or response you actually need.
5. Slow Pages and Heavy Assets
If the page is genuinely slow, reduce what it loads. Blocking images, fonts, media, and analytics can halve load time on heavy pages and removes a common source of borderline timeouts.
Raising the timeout is occasionally correct — genuinely slow reports and exports exist — but it should be a considered decision rather than the first response.
6. Frames
Content inside an iframe requires addressing that frame first. A page-level locator will never match it, and the resulting timeout looks identical to a missing element.
Identify the frame by name or URL, then query within it.
7. Fix Checklist
- Read what the timeout was waiting for.
- Confirm the selector matches on the actual rendered page.
- Check for an overlay covering the target.
- Check whether the element is in a frame or shadow root.
- Use
domcontentloadedplus an explicit wait rather thannetworkidle. - Block unnecessary resources on heavy pages.
- Raise the timeout only after excluding the above.
8. Summary
Playwright timeouts report an unmet condition, not merely slowness. The message names the condition, and most causes are a selector that no longer matches, an overlay blocking the target, a frame boundary, or a load state that page never reaches.
Work through the condition before increasing the limit — a longer timeout on a selector that will never match simply fails more slowly.