projectdiscovery/katana · error

captcha solver init: %w

Error message

captcha solver init: %w

What it means

NewHandler calls NewSolver to construct the configured captcha solver. Any error from the solver registry lookup or the constructor (e.g. unsupported provider name) is wrapped with this prefix. It means the captcha handler could not be initialized, so no captcha solving is available for this crawl.

Source

Thrown at pkg/engine/headless/captcha/captcha.go:21

import (
	"context"
	"fmt"
	"strings"

	"github.com/go-rod/rod"
	ditcaptcha "github.com/happyhackingspace/dit/captcha"
	"github.com/projectdiscovery/gologger"
	captchajs "github.com/projectdiscovery/katana/pkg/engine/headless/captcha/js"
)

type Handler struct {
	solver Solver
}

func NewHandler(solverProvider, apiKey string) (*Handler, error) {
	solver, err := NewSolver(solverProvider, apiKey)
	if err != nil {
		return nil, fmt.Errorf("captcha solver init: %w", err)
	}

	return &Handler{
		solver: solver,
	}, nil
}

func (h *Handler) HandleIfCaptcha(ctx context.Context, page *rod.Page, pageHTML string) (bool, error) {
	if ditcaptcha.DetectCaptchaInHTML(pageHTML) == ditcaptcha.CaptchaTypeNone && !strings.Contains(pageHTML, "data-sitekey") {
		return false, nil
	}

	info, err := Identify(page)
	if err != nil {
		gologger.Debug().Msgf("captcha identification failed: %s", err)
	}

	if info == nil {

View on GitHub (pinned to e3e742739c)

Solutions

1. Check the configured provider name; it must match a registered key exactly (e.g. "capsolver") — registration happens in solver packages' init() via captcha.RegisterSolver
2. Ensure the corresponding solver package is imported/linked into the build (blank import if needed)
3. Inspect the wrapped cause (%w chain) to see the underlying NewSolver error
4. Fix the config/flag value and restart the crawl

Example fix

// before
opts.CaptchaSolverProvider = "CapSolver" // wrong case

// after
opts.CaptchaSolverProvider = "capsolver" // matches registry key

supported := map[string]bool{"capsolver": true}
p := strings.ToLower(strings.TrimSpace(solverProvider))
if !supported[p] {
	return nil, fmt.Errorf("unknown captcha solver provider %q", solverProvider)
}
handler, err := captcha.NewHandler(p, apiKey)

handler, err := captcha.NewHandler(provider, apiKey)
if err != nil {
	return fmt.Errorf("captcha handler unavailable: %w", err)
}

When it happens

Trigger: Called from Crawl when headless captcha handling is enabled with an unrecognized solverProvider string (registry lookup fails, yielding "unsupported captcha solver provider: %s") or a solver constructor fails validation.

Common situations: Typo in the CLI/config option (e.g. "capSolver", "CapSolver" instead of "capsolver"); passing an empty provider; using an older build that does not register the desired solver package.

Related errors

• unsupported captcha solver provider: %s
• unsupported captcha provider for capsolver: %s
• create task: %w
• capsolver error %s: %s
• captcha solve timed out after %s

AI-assisted analysis of projectdiscovery/katana@e3e742739c (2026-09-03). Data as JSON: /api/errors/c84ec686a0a4103b. Report an issue: GitHub.