Headless Chrome made browser automation cheap to run — no desktop, no display server, a hundred tabs a minute — and it made CAPTCHAs more likely: a browser that launches in milliseconds looks exactly like what the defenses are built to catch. This guide is about running a headless session that gets challenged less, recognising the challenge when it still appears, and solving it with the same token loop the rest of our guides use, with code for Puppeteer and the same route for Playwright and raw CDP.
Why headless trips the defences
A site's anti-bot rules do not inspect your intentions; they inspect the browser. Headless Chrome hands them the evidence:
- The user agent string. Puppeteer's default headless user agent
contains
HeadlessChrome; no human browser sends that. navigator.webdriver. Automation layers leave the flag on unless something turns it off.- The environment around the page. A machine with no GPU, no plugins, no fonts and no audio devices renders differently, and the checks read exactly those differences.
None of these signals is decisive on its own, and the checks weigh them together. A run that sends a real user agent, renders through the real pipeline and keeps a stable profile can pass where a bare default launch fails — which is why two "headless" runs of the same page can end differently, and why blaming the browser after a single challenge is the wrong reflex.
Modern defence stacks — reCAPTCHA, Cloudflare Turnstile, Amazon WAF — combine those signals with behaviour: how you move, how fast you type, whether the session has history. Headless alone does not guarantee a challenge, and a good headless setup does not prevent one; it changes how often the rules fire.
Run a credible headless session
Chrome's newer headless mode renders through the real browser pipeline, so several of the old tells are gone. Three habits cover most of the rest:
- Use the new headless mode.
headless: 'new'in Puppeteer (or--headless=newon the command line) instead of the legacy mode. - Send a current user agent. The default one announces automation. Copy the user agent of a recent stable Chrome.
- Step aside from the obvious automation flags. Chrome still sets
some defaults that a plain browser would not; the common,
documented flag
--disable-blink-features=AutomationControlledremoves the most visible one.
const puppeteer = require('puppeteer');
const browser = await puppeteer.launch({
headless: 'new',
args: ['--no-sandbox', '--disable-blink-features=AutomationControlled'],
});
const page = await browser.newPage();
await page.setUserAgent(
'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
'(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36'
);
await page.setExtraHTTPHeaders({ 'Accept-Language': 'en-US,en;q=0.9' });
await page.goto('https://www.example.com/signup');
Playwright does part of this for you: its headless build sends a Chrome-like user agent by default, which is one of the reasons the same page may behave differently under the two tools. Whatever the driver, keep the fingerprint stable between the solve and the submit: a session that changes its user agent halfway through looks worse than either version alone.
When the challenge still appears
Reading the challenge is the first step, and it is the same DOM reading for every driver:
- reCAPTCHA v2 renders inside
iframe[title*="reCAPTCHA"]and stores the answer ing-recaptcha-response; - reCAPTCHA v3 runs invisibly — no iframe, a
grecaptcha.execute()call and a key in the script URL as?render=SITEKEY; - Cloudflare Turnstile renders its own widget and writes to
cf-turnstile-response; - Interstitials (Cloudflare, Amazon WAF) replace the page entirely:
a
page.goto()that arrives at a challenge instead of your form is the headless browser meeting the rules at the door.
The details of each widget, with the field lists the API expects, are on the v2, v3 and Turnstile type pages.
The solving route, briefly
Clicking the widget from inside the headless browser is the fragile path, and stealth plugins that try to hide the automation are an armsrace you do not want to maintain. The route that holds is the same one in every article on this blog: a solving API returns the token, the page receives it.
const HttpClient = require('./lib/endcaptcha.js');
const client = new HttpClient(process.env.EC_USER, process.env.EC_PASS);
const job = await new Promise((resolve) => {
client.decode({
type: 4,
googlekey: '6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI',
pageurl: 'https://www.example.com/signup',
}).on('response', resolve);
});
if (job.error) throw new Error(job.error);
await page.evaluate((token) => {
const field = document.querySelector('[name="g-recaptcha-response"]');
if (field) {
field.value = token;
field.dispatchEvent(new Event('input', { bubbles: true }));
field.dispatchEvent(new Event('change', { bubbles: true }));
}
}, job.text);
await page.click('button[type="submit"]');
The Node client ships in the downloads of the
API documentation page; type=12 with sitekey solves
Turnstile through the same object. The Python side and the full
field-by-field rules — pageurl, proxies, polling — are in the
Selenium integration guide,
and the Playwright guide
covers the same loop from the other driver.
Puppeteer, Playwright and raw CDP
The three headless stacks share one property: the token is produced outside the browser, so any of them can inject it.
- Puppeteer gives you
page.setUserAgent,page.evaluateand the full CDP underpage.target().createCDPSession(). - Playwright ships
browser.newContext()with user agent, locale and timezone in one place — the cleanest way to keep a session consistent. - Raw CDP (Puppeteer without the sugar, or the Chrome DevTools
endpoint directly) leaves everything manual, including the user
agent via
Network.setUserAgentOverride.
Whichever stack you use, wrap the launch in one function and reuse it everywhere: the moment two scripts launch the browser with different arguments, the site sees two different visitors from the same address, and the challenges multiply for both.
The difference that matters for CAPTCHAs is not the driver; it is whether the environment stays the same between the solve and the submit. Pick the tool your automation already uses and keep the fingerprint fixed.
Troubleshooting
| What you see | What it usually means | What to do |
|---|---|---|
page.goto() lands on a challenge page |
The defences fired before your form | Read the URL and title first; solve the interstitial, then continue |
| The widget iframe never appears | The provider script is blocked or lazy | Wait for the script, check for a CSP that strips it |
| Works headed, fails headless | The fingerprint differs between the two runs | Keep the same user agent, locale and flags in both |
| Token accepted by the API, rejected by the page | pageurl differs from the URL the browser is on |
Read page.url() and solve for exactly that address |
| The challenge comes back after a few requests | Rate or history signals, not headless | Slow down, reuse the session cookies, add the proxy to both solve and submit |
target closed mid-flow |
The browser crashed or was closed by the navigation | Handle the navigation, re-open the page without recreating the whole browser if possible |
Questions developers ask
Is headless still worth it? Yes — for volume, test grids and servers. The trade is that headless needs more care with fingerprints, and the token route removes the CAPTCHA from the equation either way.
Do stealth plugins help? They move the arms race one round; the defences evolve against them. The stable approach is the token: the challenge is answered by a service, not by hiding the browser better.
Does the API care that the browser is headless? No. The solve happens server-side; the browser only injects the answer.
Mobile emulation? Useful for sites that only show mobile forms —
keep the emulated user agent and the pageurl consistent, and treat
it like any other fingerprint: one session, one identity.
How long does a solve take? The service publishes a seven-second
SLA; in practice the poll returns in seconds when the queue is free,
and decode() caps the wait for you.
Where do I start? The quick start has the same flow with cURL, and creating an account takes a minute.

