Dolibarr/dolibarr · error

Error, the captcha handler

Error message

Error, the captcha handler ${captcha} has no class file found modCaptcha${Captcha}

What it means

Before including any captcha handler, Dolibarr looks for the module file core/modules/captcha/modCaptcha<ucfirst($captcha)>.class.php. When that file does not exist, the login flow rejects the attempt with this message in the session. It indicates the configured captcha module name has no corresponding file on disk.

Solutions

1. Check Setup > Security for the selected captcha value and fix typos.
2. Install the missing captcha module so core/modules/captcha/modCaptcha<Name>.class.php exists.
3. Verify file permissions/readability of htdocs/core/modules/captcha/ after deployment.
4. Temporarily disable captcha to restore login, then fix the module.
5. Re-sync the codebase after upgrades to ensure the captcha directory was deployed.

Example fix

// before (config)
captcha = 'reyg'; // no such module
// after
captcha = 'recaptcha'; // modCaptchaRecaptcha.class.php exists

$file = DOL_DOCUMENT_ROOT.'/core/modules/captcha/modCaptcha'.ucfirst($captcha).'.class.php';
if (!is_readable($file)) { die("Captcha module '$captcha' is not installed: $file missing"); }

When it happens

Trigger: The captcha configuration set to an unknown/misspelled module name so modCaptcha<Name>.class.php cannot be found.

Common situations: Typo in the captcha setup value; captcha module directory missing after an incomplete upgrade or an rsync excluding the folder; third-party captcha module not installed on the new server.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Error, the captcha handler
• Error, the captcha handler class
• ErrorBadValueForCode
• If define NOREQUIREDB or NOREQUIRETRAN are set, you must…
• If define NOREQUIREUSER is set, you must also set…

AI-assisted analysis of Dolibarr/dolibarr@598aa4bdad (2026-09-14). Data as JSON: /api/errors/3839993786b40560. Report an issue: GitHub.

Appendix: source

Thrown at htdocs/main.inc.php:664

				if (class_exists($classname)) {
					/** @var ModeleCaptcha $captchaobj */
					$captchaobj = new $classname($db, $conf, $langs, $user);
					'@phan-var-force ModeleCaptcha $captchaobj';

					if (is_object($captchaobj) && method_exists($captchaobj, 'validateCodeAfterLoginSubmit')) {
						$ok = $captchaobj->validateCodeAfterLoginSubmit(); // @phan-suppress-current-line PhanUndeclaredMethod
					} else {
						$_SESSION["dol_loginmesg"] =  'Error, the captcha handler '.get_class($captchaobj).' does not have any method validateCodeAfterLoginSubmit()';
						$test = false;
						$error++;
					}
				} else {
					$_SESSION["dol_loginmesg"] =  'Error, the captcha handler class '.$classname.' was not found after the include';
					$test = false;
					$error++;
				}
			} else {
				$_SESSION["dol_loginmesg"] = 'Error, the captcha handler '.$captcha.' has no class file found modCaptcha'.ucfirst($captcha);
				$test = false;
				$error++;
			}

			// Process error of captcha validation
			if (!$ok) {
				dol_syslog('--- Security warning: Bad value for code, connection refused', LOG_NOTICE);
				// Load translation files required by page
				$langs->loadLangs(array('main', 'errors'));

				$_SESSION["dol_loginmesg"] = (empty($_SESSION["dol_loginmesg"]) ? "" : $_SESSION["dol_loginmesg"]."<br>\n").$langs->transnoentitiesnoconv("ErrorBadValueForCode");
				$test = false;

				// Call trigger for the "security events" log
				$user->context['audit'] = 'ErrorBadValueForCode - login='.GETPOST("username", "alpha", 2);

				// Call trigger
				$result = $user->call_trigger('USER_LOGIN_FAILED', $user);

View on GitHub (pinned to 598aa4bdad)