Puppeteer: TimeoutError: Waiting for selector failed

page.waitForSelector() (or frame.waitForSelector()) polled for the selector for its whole timeout, 30 seconds by default, and the condition was never met. In current Puppeteer the timeout detail is attached as the error's cause; older releases printed it on the same line, for example Waiting for selector `.results` failed: Waiting failed: 30000ms exceeded.

By default the method only waits for the element to exist in the DOM. With { visible: true } it also requires a non-empty bounding box and no visibility: hidden; with { hidden: true } it waits for the opposite. So the same selector can succeed or time out depending on those options.

What is not wrong: the timeout length is rarely the problem. The selector either does not match what the page renders, is looked for in the wrong frame, or matches an element that never becomes visible.

try {
  await page.waitForSelector('.results', { visible: true, timeout: 15000 });
} catch (err) {
  await page.screenshot({ path: 'failure.png', fullPage: true });
  console.error(err.message, err.cause?.message);
  throw err;
}

// Locator API (Puppeteer 21+): waits, then clicks
await page.locator('button.load-more').click();

Prefer stable attributes (data-testid, name, ARIA roles via ::-p-aria()) over generated class names. Capture a screenshot and HTML on every timeout so failures are diagnosable without rerunning. Handle consent walls and empty states explicitly so they produce clear errors instead of 30-second waits.