How to Handle Cloudflare with Puppeteer

Short answer: Puppeteer cannot be used to solve Cloudflare production challenges. Cloudflare explicitly lists Puppeteer and other browser automation frameworks as unsupported for that purpose. If you own the site and need automated tests, use Cloudflare Turnstile test keys in a development or staging environment, then verify the generated token on your server with Siteverify. For a challenge loop affecting a real visitor, diagnose the active Cloudflare mechanism and browser or network conditions instead of trying to automate around it. Cloudflare’s supported-browser guidance explains the boundary.

1. Identify what Cloudflare is showing

“Cloudflare challenge” can describe different things. Identify the mechanism before changing your Puppeteer script or application code; each has a different role and troubleshooting path. See Cloudflare’s explanation of how challenges work.

Mechanism	Where it appears	What to test
Challenge Page	An interstitial page in front of the requested content, often issued through Cloudflare challenge features such as WAF rules or Bot Fight modes.	For your own site, inspect the rule or configuration that issued the challenge. Do not use Puppeteer to solve a production challenge.
Turnstile	An embedded widget in a form or other page element.	Use Turnstile test keys for automated tests. Confirm that the server validates the token with Siteverify.
JavaScript Detections	A background signal injected into HTML responses for Bot Management.	Check the WAF rule or Workers logic that consumes the signal. JavaScript Detections does not itself enforce a block.

These distinctions matter: a Turnstile widget’s token-verification flow is not the same as an interstitial Challenge Page, and JavaScript Detections is a signal rather than a challenge interaction. See the official documentation for Turnstile and JavaScript Detections.

2. Test your own Turnstile integration with Puppeteer

Use a test environment and Cloudflare-provided Turnstile test keys. Keep the test sitekey and secret separate from production credentials. The browser widget produces a token; your application server must send it to Siteverify and require a successful validation before performing the protected action. A production secret rejects dummy tokens generated with a testing sitekey. Cloudflare’s getting-started guide describes this two-part flow.

Set up the test

Create or configure a Turnstile test widget for the hostname used by your local or staging test. Get the test sitekey and matching test secret from Cloudflare’s documented test-key configuration.
Configure your application’s test environment to use that sitekey in the page and the matching test secret on the server. Do not put the secret in browser code.
Keep server-side Siteverify validation enabled in the test. A browser-visible success alone does not prove that the protected server action is guarded.
Run Puppeteer against your own test page and assert the result of the application flow, such as a success message returned only after server validation.

The code below deliberately uses environment variables for the keys and your own test URL and selectors. It does not attempt to clear, bypass, or solve a production challenge.

Runnable Puppeteer browser test

Install Puppeteer in the test project with npm install --save-dev puppeteer. Set TEST_URL to your own test form URL, and set SUCCESS_SELECTOR to an element your application renders only after successful server-side validation.

// test-turnstile.cjs
const puppeteer = require('puppeteer');

(async () => {
  const testUrl = process.env.TEST_URL;
  const successSelector = process.env.SUCCESS_SELECTOR;

  if (!testUrl || !successSelector) {
    throw new Error('Set TEST_URL and SUCCESS_SELECTOR for your test application.');
  }

  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    page.on('console', message => {
      if (message.type() === 'error') console.error('Browser console:', message.text());
    });
    page.on('pageerror', error => console.error('Page error:', error.message));

    await page.goto(testUrl, { waitUntil: 'networkidle2', timeout: 60000 });
    await page.waitForSelector('[name="email"]', { timeout: 15000 });
    await page.type('[name="email"]', 'turnstile-test@example.invalid');
    await page.click('button[type="submit"]');

    // The application should render this only after its server accepts
    // the token through Siteverify.
    await page.waitForSelector(successSelector, { timeout: 30000 });
    console.log('The test form completed its server-validated flow.');
  } finally {
    await browser.close();
  }
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

Run it after configuring the environment, for example: TEST_URL=http://localhost:3000/contact SUCCESS_SELECTOR='[data-test="form-success"]' node test-turnstile.cjs. Replace the email field, submit selector, and success selector with those in your own app. The script tests the application flow; it does not hard-code a token or assume that a client-side widget callback is sufficient.

What to assert in the application

A token reaches your application server through the form submission or your application’s chosen request.
The server sends that token to Siteverify using the matching environment secret.
The protected action succeeds only when Siteverify reports success.
Invalid, expired, reused, or missing tokens do not trigger the protected action.

Turnstile tokens can be up to 2,048 characters, expire after 300 seconds (five minutes), and can be validated only once. Tests that retry a submission should obtain a fresh token rather than reuse an earlier one. The secret belongs only on the server. See Cloudflare’s security requirements and token details.

3. Troubleshoot a genuine challenge loop

If a person using a supported browser keeps seeing a challenge, a failed attempt does not by itself show that the person is a bot or that your integration is broken. Cloudflare lists network problems, browser configuration, unsupported browsers, disabled JavaScript, and detection errors among possible causes. Work through these checks in order:

Confirm the mechanism. Is it an interstitial Challenge Page, an embedded Turnstile widget, or a Bot Management JavaScript Detection signal? Check the relevant Cloudflare feature and your own rule or application logs.
Update the browser. Try a current, supported browser. Internet Explorer, command-line clients without JavaScript, and automated browsers are not supported for solving production challenges.
Check JavaScript and extensions. Turn on JavaScript. Temporarily disable ad blockers, content blockers, script blockers, fingerprinting protection, and other extensions that can prevent challenge scripts or validation requests from working.
Check the network path. Confirm the connection is stable. Temporarily test without a VPN or proxy, then try another network such as a mobile hotspot if the issue continues.
Compare environments. Try a private window, another browser, or another device. In browser developer tools, remove user-agent, viewport, network, and JavaScript overrides. Desktop device emulation does not reproduce every property of a physical phone.
Check WebView requirements. If the issue occurs only inside a mobile app, verify JavaScript, DOM storage, cookie support, access to challenges.cloudflare.com, and a stable user agent.
Capture useful diagnostics. Reproduce with Preserve log enabled, save a HAR and browser console log, and provide them with the challenge error code and Ray ID to the site administrator or Cloudflare support.

Cloudflare notes that a 401 response on a Private Access Token request can be an expected fallback, and that some DNS lookup failures under challenge-related subdomains can be non-fatal. Do not treat either observation alone as proof of a broken widget or a blocked visitor. Follow the official challenge-solve troubleshooting guide when collecting evidence.

4. Screenshot your own test pages

For a visual record of a page you own or are authorized to test, use a normal browser screenshot in your local test run or a screenshot service against an accessible test page. A screenshot is useful for checking layout and rendered output; it does not solve a Cloudflare challenge or replace Turnstile server validation.

Local Puppeteer screenshot

// capture.cjs
const puppeteer = require('puppeteer');

(async () => {
  const url = process.env.TEST_URL;
  if (!url) throw new Error('Set TEST_URL to a page you own or are authorized to test.');
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
    await page.goto(url, { waitUntil: 'networkidle2', timeout: 60000 });
    await page.screenshot({ path: 'test-page.png', fullPage: true });
  } finally {
    await browser.close();
  }
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

This captures what the test browser rendered. If the response is an interstitial challenge, the image will reflect that; the script intentionally does not attempt to defeat it.

Or skip the browser setup

For an authorized page that can be captured, ScreenshotNeo takes a screenshot from one GET request. See the ScreenshotNeo API documentation for request options.

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

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

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

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

Performance, reliability, and cost notes

Keep browser tests focused. Launch the browser once per test or test group where your test runner permits it, close pages and browsers in cleanup paths, and use explicit timeouts so a stalled navigation fails clearly.
Do not wait forever for network idle. Applications with long polling or analytics may not become idle. If that affects your own test page, use a suitable page readiness condition such as a known form selector and assert the expected state.
Use fresh tokens. Turnstile tokens expire after five minutes and are single-use. Retrying with a stale or already redeemed token can make a valid flow appear broken.
Separate environments and secrets. Use distinct test and production configuration; never put the secret in frontend code or test logs.
Control the test conditions. Network instability, blocked scripts, extensions, VPNs, and proxies can change challenge behavior. For reproducible integration tests, use your test keys and controlled test environment.
Budget for browser resources. Headless browsers consume process and memory resources; reuse a browser process carefully and always close it in a finally block. No fixed runtime or resource figure applies to every page.
Know what a screenshot costs. ScreenshotNeo lists a free tier of 1,000 shots per month with no card; paid tiers start at $5 for 3,000. Its stated billing rule is that only clean shots are billed; inspect the response’s X-Page-Verdict and X-Billed headers for the result. Do not use screenshot capture as a substitute for challenge testing.

Common errors and fixes

Symptom	Likely cause	Fix
Puppeteer remains on a production challenge page.	Automated browsers are not supported for solving production challenges.	Stop treating the challenge as a browser-automation problem. For your own Turnstile integration, switch to test keys; for a visitor issue, diagnose the challenge and environment.
Test widget appears, but server validation fails.	The test sitekey is paired with a production secret, or the token was not sent to Siteverify.	Use the matching test secret in the test environment and validate server-side.
A retry is rejected after a previous successful submit.	The token was already validated, or it expired after five minutes.	Run the widget flow again for a fresh token before retrying.
Widget or challenge scripts fail to load.	JavaScript is disabled, a blocker or extension interferes, or the browser/network is restricted.	Enable JavaScript, temporarily disable extensions, check network stability, and try a current browser.
Only a WebView test fails.	JavaScript, DOM storage, cookies, challenge-domain access, or user-agent consistency may be missing.	Check the WebView configuration and compare against a full supported browser.
A HAR shows a 401 on a Private Access Token request.	This can be an expected fallback when a browser or network cannot issue a token.	Do not diagnose from that request alone; check whether the overall challenge completes and inspect the complete flow.
Some challenge-related DNS requests fail.	Cloudflare documents certain subdomain lookup failures as non-blocking.	Do not surface these alone as fatal integration failures; preserve errors for the challenge apex and inspect the user-visible result.
Puppeteer test times out waiting for success.	The app rejected the token, the test selector does not match, the page never reached the expected state, or navigation was delayed.	Check server Siteverify handling and application logs, confirm selectors against your page, and capture browser console errors and network diagnostics.

FAQ

Can Puppeteer pass Cloudflare?

Cloudflare says automated browsers, including Puppeteer, are unsupported for solving production challenges. Use test keys for automated Turnstile tests on your own integration.

How do I test Turnstile with Puppeteer?

Configure your development or staging site with Cloudflare’s test sitekey and matching test secret, run Puppeteer against your own page, and assert a result that only follows successful server-side Siteverify validation.

No. Your server must validate the token through Siteverify and require success before performing the protected action.

Why does Cloudflare keep showing a challenge?

First identify whether it is a Challenge Page, Turnstile widget, or JavaScript Detection enforcement path. For a genuine visitor loop, check browser support, JavaScript, extensions, network stability, VPN or proxy effects, and another browser, device, or network.

Can I screenshot a page that presents a challenge?

You can capture the page state for an authorized diagnostic, but the screenshot does not solve the challenge. Use a test environment and test keys to validate your integration.