Dolibarr/dolibarr · error

Error, the captcha handler class

Error message

Error, the captcha handler class ${classname} was not found after the include

What it means

After including the captcha module file (modCaptcha<Name>.class.php), Dolibarr instantiates the class named $classname. If the include succeeded but the class still does not exist (filename/classname mismatch), login is refused with this message stored in $_SESSION['dol_loginmesg'].

Solutions

1. Open htdocs/core/modules/captcha/modCaptcha<Name>.class.php and confirm the declared class name matches the expected 'modCaptcha'.ucfirst($captcha).
2. Rename the file or class so they match, then retry login.
3. Re-upload/restore the module file if it was truncated.
4. Check the captcha selection value in setup: a typo there changes the expected class name.

Example fix

// before: file modCaptchaRey.class.php
class modCaptchaReCaptcha extends ModeleCaptcha {}
// after
class modCaptchaRey extends ModeleCaptcha {}

include_once $file;
if (!class_exists('modCaptcha'.ucfirst($captcha))) { /* file/class mismatch */ }

When it happens

Trigger: Captcha module file included but the class declared inside does not match the expected name (modCaptcha.ucfirst($captcha)); the included file is empty or declares a different class.

Common situations: Renaming a class inside a custom captcha module without renaming the file; truncated/partial file uploads leaving a class-less file; a stub placeholder file with no class.

Related errors

• Error, the captcha handler
• Error, the captcha handler
• 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/6e25fe53f3c83c45. Report an issue: GitHub.

Appendix: source

Thrown at htdocs/main.inc.php:659

				include_once $fullpathclassfile;
				$captchaobj = null;

				// Charging the numbering class
				$classname = "modCaptcha".ucfirst($captcha);
				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;

View on GitHub (pinned to 598aa4bdad)