{"record":{"id":"c84ec686a0a4103b","repo":"projectdiscovery/katana","slug":"captcha-solver-init-w","errorCode":null,"errorMessage":"captcha solver init: %w","messagePattern":"captcha solver init: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/engine/headless/captcha/captcha.go","lineNumber":21,"sourceCode":"import (\n\t\"context\"\n\t\"fmt\"\n\t\"strings\"\n\n\t\"github.com/go-rod/rod\"\n\tditcaptcha \"github.com/happyhackingspace/dit/captcha\"\n\t\"github.com/projectdiscovery/gologger\"\n\tcaptchajs \"github.com/projectdiscovery/katana/pkg/engine/headless/captcha/js\"\n)\n\ntype Handler struct {\n\tsolver Solver\n}\n\nfunc NewHandler(solverProvider, apiKey string) (*Handler, error) {\n\tsolver, err := NewSolver(solverProvider, apiKey)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"captcha solver init: %w\", err)\n\t}\n\n\treturn &Handler{\n\t\tsolver: solver,\n\t}, nil\n}\n\nfunc (h *Handler) HandleIfCaptcha(ctx context.Context, page *rod.Page, pageHTML string) (bool, error) {\n\tif ditcaptcha.DetectCaptchaInHTML(pageHTML) == ditcaptcha.CaptchaTypeNone && !strings.Contains(pageHTML, \"data-sitekey\") {\n\t\treturn false, nil\n\t}\n\n\tinfo, err := Identify(page)\n\tif err != nil {\n\t\tgologger.Debug().Msgf(\"captcha identification failed: %s\", err)\n\t}\n\n\tif info == nil {","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/projectdiscovery/katana/blob/e3e742739c3746f085943ce918fb4e2b8daf6fe6/pkg/engine/headless/captcha/captcha.go#L3-L39","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the configured provider name; it must match a registered key exactly (e.g. \"capsolver\") — registration happens in solver packages' init() via captcha.RegisterSolver","Ensure the corresponding solver package is imported/linked into the build (blank import if needed)","Inspect the wrapped cause (%w chain) to see the underlying NewSolver error","Fix the config/flag value and restart the crawl"],"exampleFix":"// before\nopts.CaptchaSolverProvider = \"CapSolver\" // wrong case\n\n// after\nopts.CaptchaSolverProvider = \"capsolver\" // matches registry key","handlingStrategy":"validation","validationCode":"supported := map[string]bool{\"capsolver\": true}\np := strings.ToLower(strings.TrimSpace(solverProvider))\nif !supported[p] {\n\treturn nil, fmt.Errorf(\"unknown captcha solver provider %q\", solverProvider)\n}\nhandler, err := captcha.NewHandler(p, apiKey)","typeGuard":null,"tryCatchPattern":"handler, err := captcha.NewHandler(provider, apiKey)\nif err != nil {\n\treturn fmt.Errorf(\"captcha handler unavailable: %w\", err)\n}","preventionTips":["Use exact lowercase provider names from the library docs","Ensure solver packages are imported into the build","Fail fast at config load with a provider whitelist","Trim/case-normalize config values"],"tags":["captcha","initialization","config-error"],"backgroundTag":"invalid-config-option","analyzedSha":"e3e742739c3746f085943ce918fb4e2b8daf6fe6","analyzedAt":"2026-09-03T14:55:13.248Z","contentChangedAt":"2026-09-03T14:55:13.248Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}