How to Fix Puppeteer Clicks That Work Only Occasionally

Use Puppeteer’s locator API first: await page.locator(selector).click(). A locator waits for the element to be present, in the viewport, visible, enabled, and stable across two animation frames before clicking. If the click navigates, begin waitForNavigation() at the same time as the click. Then verify the result your application promises, such as a URL, dialog, or success element.

Intermittent clicks do not have one universal cause. The page may still be rendering, the selector may match the wrong control, an animation may move the target, or the click may succeed while your script races the resulting navigation. The sections below show a repeatable way to separate those cases.

1. Replace a bare click with a locator

Puppeteer describes locators as the recommended way to select and interact with elements. The locator click performs readiness checks that a simple DOM presence check does not. See the Page interactions guide.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();

await page.goto('https://example.com/login', { waitUntil: 'domcontentloaded' });

await page.locator('button[type="submit"]').click();

await browser.close();

During a locator click, Puppeteer waits for viewport placement, visibility, enabled state, and a stable bounding box over two consecutive animation frames. This handles many delayed-rendering and layout-shift cases without an arbitrary sleep.

Make the selector unique

A selector should identify the intended control on every run. Prefer a stable ID, an accessible role or name, or a test attribute owned by your application.

// More specific than a generic "button" selector:
await page.locator('button[data-testid="checkout-submit"]').click();

// Use an accessible name when the page exposes one:
await page.getByRole('button', { name: 'Submit order' }).click();

If a selector can match several controls, inspect the page and refine it. A repeated header button, hidden mobile menu, or duplicate dialog action can make a click appear random even when Puppeteer is behaving consistently.

2. Coordinate clicks with navigation

When a click starts a document navigation or reload, start the navigation wait before the click. Puppeteer documents this Promise.all pattern because waiting after the click can miss a fast navigation. The Page API documentation shows the same coordination for page.click(); the same timing principle applies to a locator click.

const [response] = await Promise.all([
  page.waitForNavigation({ waitUntil: 'networkidle0' }),
  page.locator('a[href="/dashboard"]').click()
]);

console.log('Loaded:', response?.url());

Choose navigation options that match the site. domcontentloaded finishes when the document is parsed; networkidle0 waits for no active network connections and can take longer on applications with polling. History API URL changes also count as navigation in Puppeteer.

Do not use a navigation wait for a button that updates the current page without navigation. Wait for the application result instead:

await page.locator('button[data-testid="save"]').click();
await page.locator('[role="status"]').wait({
  visible: true,
  timeout: 10_000
});

3. Understand what waitForSelector does—and does not do

waitForSelector() waits until a matching node is in the DOM. With visible: true, it additionally requires that the element is not display: none or visibility: hidden. It does not by itself guarantee that the element is enabled, inside the viewport, or no longer moving. See the waitForSelector API.

await page.waitForSelector('button[type="submit"]', {
  visible: true,
  timeout: 15_000
});
await page.locator('button[type="submit"]').click();

Use this lower-level wait when you need to establish DOM presence or visibility for diagnostics. Keep the locator click as the action that performs the stronger readiness checks.

4. A complete diagnostic script

This script records the selector, versions, URL, and useful element state. It also distinguishes a navigation outcome from a same-page outcome.

import puppeteer from 'puppeteer';

const selector = 'button[data-testid="save"]';
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
page.setDefaultTimeout(15_000);

page.on('console', message => console.log('[page]', message.text()));
page.on('pageerror', error => console.error('[page error]', error.message));

try {
  await page.goto('https://example.com/editor', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000
  });

  const details = await page.$eval(selector, element => {
    const style = getComputedStyle(element);
    const rect = element.getBoundingClientRect();
    return {
      tag: element.tagName,
      disabled: 'disabled' in element && element.disabled,
      display: style.display,
      visibility: style.visibility,
      rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
    };
  });
  console.log(details);

  await page.locator(selector).click();
  await page.locator('[role="status"]').wait({ visible: true });
} catch (error) {
  await page.screenshot({ path: 'click-failure.png', fullPage: true });
  console.error({
    message: error.message,
    url: page.url(),
    selector,
    puppeteer: puppeteer.version
  });
  throw error;
} finally {
  await browser.close();
}

5. Diagnose the failure in a fixed order

1. Confirm the target. Log how many elements match, inspect their text and attributes, and check whether the intended element is inside an iframe or shadow root.
2. Use a locator click. If it times out, the error usually points to delayed appearance, invisibility, disabled state, movement, or an incorrect selector.
3. Check the frame. A selector in an iframe must be resolved through that frame.
4. Coordinate navigation. Use Promise.all only when the click is expected to navigate.
5. Verify the outcome. A resolved click promise means the input was dispatched; it does not prove that saving, submitting, or routing completed.
6. Capture evidence. Record the browser and Puppeteer versions, URL, selector, frame, timeout, element state, screenshot, and page errors from the failing run.

Frames

const frame = page.frames().find(f => f.url().includes('/checkout-widget'));
if (!frame) throw new Error('Checkout frame was not found');
await frame.locator('button[type="submit"]').click();

Shadow DOM

Puppeteer selectors and locators support shadow-root traversal. Use a selector that reflects the component structure, or inspect the installed version’s locator documentation before relying on version-specific syntax. The Locator API lists the available controls.

6. Common errors and fixes

Symptom	Likely cause	Fix
Timeout waiting for locator	Wrong selector, delayed render, hidden or disabled control, or moving layout	Inspect matching nodes; refine the selector; wait for the application state; use a locator timeout appropriate for the page.
Click works only after a sleep	Timing or animation race	Replace the sleep with a locator click and wait for the actual ready state or success signal.
Navigation wait hangs	The click does not navigate, or the chosen lifecycle event never becomes idle	Remove waitForNavigation() for same-page actions, or use a less strict waitUntil value.
Navigation is missed	The wait starts after the click	Start waitForNavigation() and the click in one Promise.all.
Wrong control is clicked	Generic selector matches multiple or hidden controls	Use a unique ID, role/name, or test attribute and inspect all matches.
Element is present but unusable	waitForSelector checked presence only	Use a locator click, which also checks enabled state, viewport placement, and box stability.
Click inside an embedded widget fails	Target is in an iframe	Find the correct frame and run the locator against that frame.
Chrome warning page appears	A specific remote-navigation Chrome-for-Testing warning page	Inspect the page for its continuation control; treat this as a navigation-specific symptom. See Puppeteer’s troubleshooting guide.

7. Reliability and performance practices

• Prefer deterministic selectors owned by the application.
• Set a deliberate default timeout and override it for known slow operations.
• Wait for a state that proves the business action completed, rather than adding a fixed delay.
• Keep navigation waits and clicks in one promise when navigation is expected.
• Save a failure screenshot and structured diagnostics; avoid retrying blindly because retries can submit a form twice.
• Reuse a browser process when capturing many pages, but create isolated pages and close them reliably.
• Choose the least expensive lifecycle condition that is sufficient for the page. Waiting for network idle can be slower on sites with analytics or polling.

Retries are appropriate only when the operation is idempotent or you can detect that it did not complete. A retry cannot repair a selector that targets the wrong element or a click that triggers an unintended side effect.

8. Or skip the browser setup

If your goal is a reliable image of a page rather than browser interaction itself, ScreenshotNeo provides a single GET request that returns PNG, JPEG, WebP, or PDF. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options, including full-page and element capture, custom CSS and JavaScript, waits, request blocking, headers, cookies, device presets, PDFs, caching, signed links, asynchronous jobs, bulk capture, and usage data.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

There are 1,000 free screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account.

9. Short FAQ

Should I always use waitForSelector before clicking?

No. A locator click already waits for the action’s readiness conditions. Use waitForSelector when you specifically need a DOM-presence or visibility check.

Does a successful click promise mean the form submitted?

No. Wait for the resulting URL, response, status message, or other page-specific success state.

Can I fix intermittent clicks by increasing the timeout?

Only when the page is legitimately slow. A longer timeout does not fix an ambiguous selector, wrong frame, disabled control, or missing navigation coordination.

What should I include in a bug report?

Include the selector, URL, frame, Puppeteer and browser versions, exact error, expected outcome, element state, and a screenshot from the failing run.