Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
A Puppeteer waitForSelector() timeout means the requested condition was not met before the configured limit. The default is 30,000 milliseconds (30 seconds), so the reliable fix is to inspect the live page, verify the selector and browsing context, confirm whether presence or visibility is required, and only then adjust a justified timeout. A longer wait cannot fix a selector that never matches.
What the timeout actually means
page.waitForSelector(selector) waits for the selector to appear in the page. If it does not appear before the configured timeout, Puppeteer throws an error such as Waiting for selector failed: timeout 30000ms exceeded. The documented default is 30,000 milliseconds, and page.setDefaultTimeout() changes that default for subsequent operations.
By default, Puppeteer only requires a matching element in the document. It does not require the element to be visible unless you request that condition. A timeout therefore usually points to one of five problems: the selector no longer matches, the page is not the page you expected, the element is in another frame, the application has not rendered it yet, or your visibility condition is impossible.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Diagnose the live page before changing the timeout
Run diagnostics at the point where the wait fails. Do not rely on what you saw manually in a browser tab; the automated page can have a different URL, cookies, viewport, timing, or markup.
#1 Best Overall
- KEYBOARD: The keyboard works for Windows with hot keys that enable easy access to Media, My Computer, Mute, Volume up/down, and Calculator
- EASY SETUP: Experience simple installation with the USB wired connection
- VERSATILE COMPATIBILITY: This keyboard is designed to work with multiple Windows versions, including Vista, 7, 8, 10 offering broad compatibility across devices.
- SLEEK DESIGN: The elegant black color of the wired keyboard complements your tech and decor, adding a stylish and cohesive look to any setup without sacrificing function.
- FULL-SIZED CONVENIENCE: The standard QWERTY layout of this keyboard set offers a familiar typing experience, ideal for both professional tasks and personal use.
try {
await page.waitForSelector('[data-testid="results"]');
} catch (error) {
await page.screenshot({ path: 'timeout-state.png', fullPage: true });
console.error('URL:', await page.url());
console.error('Frames:', page.frames().map(frame => frame.url()));
console.error((await page.content()).slice(0, 5000));
throw error;
}Compare the captured HTML with the selector character for character. Also inspect browser console messages and failed network requests; a JavaScript exception, redirect, authentication page, or blocked request can prevent the component from ever being created.
Confirm the selector
- Check CSS punctuation, brackets, quotes, commas, and escaping. A malformed attribute selector can wait until timeout instead of matching anything.
- Check case-sensitive attribute values and whether a class name is generated differently on each build.
- Prefer stable attributes such as
data-testidwhen your application provides them, rather than styling classes that may change. - Verify that hydration or a client-side route does not replace the server-rendered component with a different structure.
- Remember that Puppeteer accepts CSS selectors and its documented Puppeteer-specific selector syntax; a selector that is valid in one context may not identify the rendered node in another.
Check presence versus visibility
The visible and hidden options change what success means. Both default to false.
| Option | What Puppeteer waits for | Typical use |
|---|---|---|
| Neither option | A matching element exists in the DOM. | Reading text or attributes from an element that may be off-screen. |
visible: true |
A matching element exists and is visible. display: none and visibility: hidden do not satisfy it. |
Clicking a control or reading content users can see. |
hidden: true |
The element is absent or hidden. | Waiting for a loading mask, modal, or progress indicator to finish. |
Do not combine a visibility assumption with a selector that targets a hidden template node. If the application intentionally keeps the node hidden until another action, wait for that action’s result instead.
Use the correct browsing context
An iframe has its own document. Calling page.waitForSelector() searches the main document, not every attached frame. Find the relevant Frame and call the frame-scoped method.
Rank #2
- Reliable Plug and Play: The USB receiver provides a reliable wireless connection up to 33 ft (1), so you can forget about drop-outs and delays and you can take it wherever you use your computer
- Type in Comfort: The design of this keyboard creates a comfortable typing experience thanks to the low-profile, quiet keys and standard layout with full-size F-keys, number pad, and arrow keys
- Durable and Resilient: This full-size wireless keyboard features a spill-resistant design (2), durable keys and sturdy tilt legs with adjustable height
- Long Battery Life: MK270 combo features a 36-month keyboard and 12-month mouse battery life (3), along with on/off switches allowing you to go months without the hassle of changing batteries
- Easy to Use: This wireless keyboard and mouse combo features 8 multimedia hotkeys for instant access to the Internet, email, play/pause, and volume so you can easily check out your favorite sites
const frame = page.frames().find(frame => frame.url().includes('/embedded/'));
if (!frame) {
throw new Error('Expected embedded frame was not attached');
}
await frame.waitForSelector('.result', { visible: true });If the frame URL is initially empty or changes during navigation, identify it after the frame has attached and after the navigation that creates it. A selector copied from the top-level page will still time out when the real element lives inside an iframe.
Verify navigation and rendering order
waitForSelector() can be used across navigations, but it only succeeds in the page or frame that is currently being watched. Log the URL after each navigation and make sure the wait follows the operation that causes the element to appear.
await page.goto('https://example.com/search', { waitUntil: 'domcontentloaded' });
console.log('After navigation:', await page.url());
await page.click('[data-testid="submit-search"]');
await page.waitForSelector('[data-testid="results"]', { visible: true });Waiting for a selector immediately after goto() can be too early for a client-rendered application. Conversely, waiting for a selector from the previous route after a redirect guarantees a timeout. Treat the URL, frame list, and rendered HTML as the ground truth.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Increase the timeout only when the page is legitimately slow
Use a local timeout for a known slow operation so unrelated waits retain their normal limit:
Rank #3
- All-day Comfort: The design of this standard keyboard creates a comfortable typing experience thanks to the deep-profile keys and full-size standard layout with F-keys and number pad
- Easy to Set-up and Use: Set-up couldn't be easier, you simply plug in this corded keyboard via USB on your desktop or laptop and start using right away without any software installation
- Compatibility: This full-size keyboard is compatible with Windows 7, 8, 10 or later, plus it's a reliable and durable partner for your desk at home, or at work
- Spill-proof: This durable keyboard features a spill-resistant design (1), anti-fade keys and sturdy tilt legs with adjustable height, meaning this keyboard is built to last
- Plastic parts in K120 include 51% certified post-consumer recycled plastic*
await page.waitForSelector('[data-testid="reports"]', { timeout: 60000 });Use page.setDefaultTimeout(60000) when the whole workflow has a documented reason to use a longer default. Passing timeout: 0 disables the wait timeout. That is safe only when another external completion condition guarantees the operation will finish; otherwise a missing selector can leave the run waiting indefinitely.
A useful rule is to fix correctness first, then timing. If the selector, frame, and condition are wrong, increasing 30 seconds to 120 seconds merely delays the same failure. If the element consistently appears after a slow API response, a narrowly scoped increase is easier to observe and less likely to hide regressions.
A complete debugging pattern
This script records the failure state, distinguishes a visibility requirement, and rethrows the original error so your test runner still reports a failure.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
page.on('console', message => console.log('[browser]', message.type(), message.text()));
page.on('requestfailed', request => {
console.error('[request failed]', request.url(), request.failure()?.errorText);
});
try {
await page.goto('https://example.com/app', {
waitUntil: 'domcontentloaded',
timeout: 45000
});
const target = '[data-testid="results"]';
await page.waitForSelector(target, { visible: true, timeout: 30000 });
console.log('Results are visible');
} catch (error) {
await page.screenshot({ path: 'wait-failure.png', fullPage: true });
console.error('Failed URL:', await page.url());
console.error('HTML preview:', (await page.content()).slice(0, 5000));
throw error;
} finally {
await browser.close();
}
})();Replace the example URL and selector with values from your application. The screenshot, URL, and HTML logging are diagnostic steps; Puppeteer does not automatically perform that investigation for you.
Rank #4
- 【Dreamy Rainbow Gaming Keyboard】K521 Gaming Keyboard Adopts a Different LED Backlight Design, Upgraded on the Traditional LED Backlight Effect, Making the Light More Penetrating, Giving You a More Dazzling Visual Effect, Making Your Gaming Process More Enjoyable
- 【One Touch Opens & Visual Feast】The K521 Red Dragon Keyboard has a One-Touch on/off Lighting Button for Added Convenience. It also has a Three-Position Adjustable Breathing Mode and a Four-Position Adjustable Brightness Lighting Mode
- 【Mechanical Feeling & Fast Tapping】The PC Keyboard Keys are Designed for Mechanical Feeling, Giving You a Better Feel During Use and the Ability to Trigger Keys Quickly, Allowing You to Win All Your Games
- 【19 Keys Anti-Ghosting Keyboard】Anti-Ghosting Ensures Every Button Can Be Triggered. This Allows You to Trigger Key Combinations In The Game Accurately, And Each Skill Can Be Accurately Released to Increase Your Winning Rate. Redragon K521 Will Be Your Perfect Partner
- 【12 Multimedia Combination Keys】The K521 Wired Gaming Keyboard is Equipped with 12 Multimedia Keys That Can Greatly Enhance Your Gaming/Office Efficiency and Make It More Convenient to Use
Common timeout symptoms and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The element is visible in a normal browser but times out in automation. | The automated page was redirected, lacks required state, or rendered different markup. | Log page.url(), save page.content(), and inspect console and request failures at the failure point. |
HTML contains the text, but visible: true times out. |
The matching node is hidden, covered by the app’s state, or is a hidden template. | Inspect computed state in the captured page and wait for the visible node or the state transition that reveals it. |
| A selector works on one run and fails on another. | Dynamic classes, race conditions, or a variable rendering path. | Use a stable attribute and wait for the application state that creates it, rather than a fixed arbitrary delay. |
| The main page never finds a selector that appears in a widget. | The widget is inside an iframe. | Locate the expected Frame and call frame.waitForSelector(). |
| The timeout is always exactly 30,000 ms. | The operation is using Puppeteer’s documented default. | Correct the selector or context first; set a local timeout only if rendering is demonstrably slower. |
| A wait hangs after setting timeout to zero. | No external completion condition can prove that the selector will appear. | Restore a finite timeout and investigate the page state instead of disabling the limit. |
Make waits reliable in CI
- Capture the URL, HTML preview, screenshot, console output, and failed requests whenever a wait fails. These artifacts turn an intermittent failure into an inspectable state.
- Keep timeout changes local where possible. A global default can make unrelated failures slower and obscure which operation is actually slow.
- Use a selector that describes the component’s contract, not an implementation detail that changes during builds.
- Separate navigation completion from application rendering. A completed document navigation does not prove that a client-side result has been inserted.
- When using frames, record frame URLs and select the frame after it is attached or navigated, rather than assuming the first frame remains the target.
Or skip the browser setup
If your goal is a clean image or PDF of a URL rather than interactive browser testing, ScreenshotNeo provides a single HTTP request. Before capture it accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the page verdict and billing result in X-Page-Verdict and X-Billed headers. Its MCP server supplies take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
For the complete option list and parameter details, see the ScreenshotNeo documentation.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo supports PNG, JPEG, WebP, or PDF output plus full-page capture with lazy images, CSS-selector element capture, device presets, custom viewports, retina scale, waits, custom JavaScript and CSS, click and hide actions, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Its parameter names are compatible with those used by other screenshot APIs, which can simplify migration.
Every feature is included on every plan. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Yearly billing provides two months free. Create a free ScreenshotNeo account to start without a card.
FAQ
Does a successful selector wait prove that the page is ready?
No. It proves only that the requested condition for that selector was met in the page or frame being watched. Other data, images, or controls may still be loading, so choose a condition that represents the state your test actually needs.
Best Value
- All-day Comfort: This USB keyboard creates a comfortable and familiar typing experience thanks to the deep-profile keys and standard full-size layout with all F-keys, number pad and arrow keys
- Built to Last: The spill-proof (2) design and durable print characters keep you on track for years to come despite any on-the-job mishaps; it’s a reliable partner for your desk at home, or at work
- Long-lasting Battery Life: A 24-month battery life (4) means you can go for 2 years without the hassle of changing batteries of your wireless full-size keyboard
- Simply plug the USB receiver into a USB port on your desktop, laptop or netbook computer and start using the keyboard right away without any software installation
- Simply Wireless: Forget about drop-outs and delays thanks to a strong, reliable wireless connection with up to 33 ft range (5); K270 is compatible with Windows 7, 8, 10 or later
Should I use a fixed delay instead of waitForSelector()?
A fixed delay does not verify that the required element exists and can make fast runs slower while still failing on slow runs. Waiting for the selector, with a justified timeout, ties progress to an observable page condition.
Why should the failure artifacts be captured before closing the browser?
The URL, DOM, console messages, frame list, and screenshot describe the exact state in which the wait failed. Closing the browser first discards that evidence and leaves only the generic timeout message.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Frequently Asked Questions
Can I use the same selector on the page and an iframe?
No. The selector is evaluated in the document represented by the object on which you call the method. Use the page for the top-level document and the matching Frame object for an iframe.
When is a longer timeout a reasonable fix?
When diagnostics show that the correct element reliably appears after a slow but bounded render or API operation. Keep the increase local and retain a finite limit.
What should I record when the failure is intermittent?
Record the URL, frame URLs, rendered HTML, screenshot, browser console messages, and failed network requests at the moment of failure; compare successful and failed runs for differences.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →
