Skip to content

Node.js Captcha Solver Module for Puppeteer ​

The capguru module solves captchas right on the page your Puppeteer script controls: it clicks images, drags sliders and handles other tasks, and it can detect the captcha type on the page automatically. Starting with version 0.5.0, it also gets reCAPTCHA and Cloudflare Turnstile tokens, recognizes text captchas and works without a browser.

You can test your script on the captcha demo pages. If you work in Python, there is the same Python module for Playwright and Selenium.

Versions ​

Module VersionDownloadChanges
0.5.0npm � 0.5reCAPTCHA v2/v3 (Enterprise) and Cloudflare Turnstile tokens, text captchas, client without a browser, timeouts and CapGuruSolveError
0.40.4Global update, automatic captcha detection auto(), added AWS WAF

Installation ​

The module is published on npm:

bash
npm install capguru puppeteer
javascript
const { CaptchaSolver, CapGuruFatalError, CapGuruSolveError } = require('capguru');

Update to the latest version:

bash
npm install capguru@latest
Installation without npm

Download the archive from the version table, copy the capguru folder into your project and install Puppeteer:

bash
npm install puppeteer

Then import it with a relative path: require('./capguru').

Usage ​

  1. Import CaptchaSolver from the package.
  2. Launch the browser as in the example below, create the solver before navigating to the page with the captcha, and call await solver.setup().
  3. Open the page and call await solver.auto(): the module will find the captcha and solve it.

If you know the captcha type in advance, you can call the specific method directly.

javascript
const puppeteer = require('puppeteer');
const { CaptchaSolver, CapGuruFatalError } = require('capguru');

(async () => {
  const browser = await puppeteer.launch({
    headless: false,
    ignoreDefaultArgs: ['--enable-automation'],
    args: ['--disable-blink-features=AutomationControlled'],
  });
  const page = await browser.newPage();

  const solver = new CaptchaSolver({
    page,
    apiKey: 'YOUR_CAPGURU_API_KEY',
    debug: true,
    attempts: 5,
  });
  await solver.setup();

  await page.goto('https://example.com/with-captcha');

  try {
    const kind = await solver.auto(30);
    console.log('Captcha:', kind || 'not found');
  } catch (e) {
    if (e instanceof CapGuruFatalError) console.log('API key or balance problem:', e.message);
    else console.log('Not solved:', e.message);
  } finally {
    await browser.close();
  }
})();

Why the solver is created before navigation

When created, the solver starts capturing the captcha images loaded by the browser and switches hCaptcha to English. If you create it after page.goto(), images from the first load will be missed and hCaptcha may stay in the site's language.

Why the browser is launched with these options

With the default Puppeteer launch, sites see that the browser is controlled by a program (navigator.webdriver is true), and Google and GeeTest show harder challenges or refuse. The options in the example turn this off.

Methods ​

Automatic:

await solver.auto(30);      // find and solve the captcha, returns its type or null
await solver.detect();      // only detect the type, without solving
await solver.setup();       // preparation, call before page.goto()

auto() does not solve Cloudflare Turnstile and reCAPTCHA v3: use the token methods below for them.

Solving on the page, for a specific type:

await solver.solveRecaptcha2();
await solver.solveHcaptcha();
await solver.solveOther();       
await solver.solveGeetest();
await solver.solveFuncaptcha();
await solver.solveTiktok();
await solver.solveAws();

Tokens and text captchas (since 0.5.0):

await solver.solveRecaptchaToken();     // reCAPTCHA v2 or v3, detected from the page
await solver.solveRecaptchaToken({ version: 'v3', action: 'login', enterprise: true });
await solver.solveTurnstileToken();     // Cloudflare Turnstile
await solver.solveImageCaptcha('#captcha_img', { fillSelector: '#captcha_input' });
await solver.getBalance();              // account balance
solver.cancel();                        // stop the current solve
  • solveRecaptchaToken() and solveTurnstileToken() find the sitekey, action and Enterprise flag on the open page and put the token into it: reCAPTCHA v2 into g-recaptcha-response and the site callback, Turnstile into cf-turnstile-response and data-callback. They return { token, taskId }. For v3, action defaults to verify.
  • solveImageCaptcha() sends the image shown on the page (a screenshot of the element) and never downloads it again: many sites return a new captcha on every request. With fillSelector, it types the answer into the input. It returns { text, taskId }.

auto() and detect() return the captcha type:

ValueCaptcha
recaptcha2reCAPTCHA v2
hcaptchahCaptcha
yandexOther
geetestGeeTest v3 / v4
funcaptchaFunCaptcha (Arkose Labs)
tiktokTikTok
awsAWS WAF
nullNo captcha found within the timeout

auto() parameters:

ParameterTypeDefaultDescription
timeoutnumber30How many seconds to wait for a captcha to appear. On slow sites, 45 to 60 is safer
pollnumber0.5How often to check the page, in seconds

Without a Browser ​

You can get tokens and recognize text captchas without Puppeteer, with the API client:

javascript
const { CapGuruClient } = require('capguru');
const client = new CapGuruClient('YOUR_KEY');   // https://api2.cap.guru by default, falls back to https://api.cap.guru

await client.getBalance();
await client.recaptchaV2Token({ sitekey, pageurl, invisible: false });
await client.recaptchaV3Token({ sitekey, pageurl, action: 'verify', enterprise: false });
await client.turnstileToken({ sitekey, pageurl });
await client.imageText(bufferOrBase64, { vernet: 0 });   // vernet 22 = arithmetic, the result is calculated
await client.solveTask({ method: 'geetest', gt, challenge, pageurl });   // any other task

Token methods return { token, taskId }, imageText returns { text, taskId } (plus expression for arithmetic). enterprise: true sends enterprise=1 (v3 only).

Supported Captchas ​

CaptchaOn the pageToken
reCAPTCHA v2 / v2 InvisibleYesYes
reCAPTCHA v3 / v3 EnterpriseYes
Cloudflare TurnstileYes
hCaptchaYes
OtherYes
GeeTest v3 / v4Yes
FunCaptchaYes
TikTokYes
AWS WAFYes
Text captchasYes

Constructor Parameters ​

ParameterTypeDefaultDescription
pagePagenonePuppeteer page instance
apiKeystringnoneCap.Guru API key
serverstring'https://api.cap.guru'API server URL. Outside Russia, use 'https://api2.cap.guru'
attemptsnumber5Max number of solving attempts. For GeeTest and FunCaptcha, 8 to 10 work better: they often show several rounds of images in a row
timeoutnumber300How many seconds a captcha solve on the page may take. Can also be set per call: solver.solveGeetest('', { timeout: 120 })
debugbooleanfalseEnable debug logging
selectorstring''CSS selector of the captcha container, if the page has several captchas

For tokens and text captchas, the default wait time is 120 seconds; set it with the timeout option of each method.

Requirements ​

  • Puppeteer 24 or 25
  • Node.js 18 or newer (Puppeteer 25 requires Node.js 22.12 or newer)

Error Handling ​

  • CapGuruFatalError: an invalid API key or zero balance. The module stops retrying immediately.
  • CapGuruSolveError: the captcha could not be solved after all attempts, or the time ran out. For tokens and text captchas the error includes taskId.

Both classes are subclasses of Error:

javascript
const { CapGuruFatalError, CapGuruSolveError } = require('capguru');

try {
  const kind = await solver.auto(30);
  console.log('Captcha:', kind || 'not found');
} catch (e) {
  if (e instanceof CapGuruFatalError) {
    console.log('API key or balance problem:', e.message);
  } else if (e instanceof CapGuruSolveError) {
    console.log('Captcha not solved:', e.message);
  } else {
    throw e;
  }
}

What the API error codes mean is explained on the error codes page.