What causes "Authentication handler is disabled" in apereo/cas?

Enable the authentication feature/module that supplies the real handler (add dependency or enable feature flag)

apereo/cas · error · PreventedException

Authentication handler is disabled

Error message

Authentication handler is disabled

What it means

AuthenticationHandler.disabled() returns a placeholder handler whose authenticate() immediately throws PreventedException('Authentication handler is disabled'). It is a no-op used when a handler type is configured but its feature is disabled, guaranteeing it never authenticates credentials.

Solutions

Enable the authentication feature/module that supplies the real handler (add dependency or enable feature flag)
Remove the disabled handler from the execution plan so other handlers can support the credential
Inspect configuration/logs to find why the real handler was replaced by the disabled stub

Example fix

// before
AuthenticationHandler handler = AuthenticationHandler.disabled();
// after
AuthenticationHandler handler = new MyLdapAuthenticationHandler(ldapAuthenticator, servicesManager);

Defensive patterns

Strategy: validation

Validate before calling

// before authenticating, ensure the handler is not the disabled stub
if (handler == AuthenticationHandler.disabled()) {
    throw new IllegalStateException("Handler feature is disabled; enable its module/feature flag");
}

Try / catch

try {
    AuthenticationResult r = transactionManager.authenticate(transaction);
} catch (PreventedException e) {
    if ("Authentication handler is disabled".equals(e.getMessage())) {
        LOGGER.error("Feature-disabled handler used; enable the owning module");
    }
}

Prevention

Enable the CAS module/feature that supplies the real handler
Do not wire AuthenticationHandler.disabled() in production configs
Audit the authentication execution plan at startup for disabled handlers

When it happens

Trigger: A handler bean registered as AuthenticationHandler.disabled() receives a credential during an authentication transaction, typically because the real module/feature is disabled via @ConditionalOnFeatureEnabled or a missing dependency.

Common situations: CAS module owning the real handler not on the classpath, feature flag off, or custom code explicitly wiring the disabled stub instead of a real handler.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/d6787a4fbd848c82. Report an issue: GitHub.

Appendix: source

Thrown at api/cas-server-core-api-authentication/src/main/java/org/apereo/cas/authentication/AuthenticationHandler.java:35

 * @author Marvin S. Addison
 * @since 4.0.0
 */
@FunctionalInterface
public interface AuthenticationHandler extends Ordered, NamedObject {

    /**
     * Attribute name containing collection of handler names that successfully authenticated credential.
     */
    String SUCCESSFUL_AUTHENTICATION_HANDLERS = "successfulAuthenticationHandlers";

    /**
     * Disabled authentication handler.
     *
     * @return the authentication handler
     */
    static AuthenticationHandler disabled() {
        return (credential, service) -> {
            throw new PreventedException("Authentication handler is disabled");
        };
    }

    /**
     * Authenticates the given credential. There are three possible outcomes of this process, and implementers
     * MUST adhere to the following contract:
     *
     * <ol>
     * <li>Success -- return {@link AuthenticationHandlerExecutionResult}</li>
     * <li>Failure -- throw {@link GeneralSecurityException}</li>
     * <li>Indeterminate -- throw {@link PreventedException}</li>
     * </ol>
     *
     * @param credential The credential to authenticate.
     * @param service    the requesting service, if any.
     * @return A result object containing metadata about a successful authentication event that includes at a
     * minimum the name of the handler that authenticated the credential and some credential metadata. The following data
     * is optional: <ul> <li>{@link Principal}</li> <li>Messages issued by the handler about the credential (e.g. impending password expiration warning)</li> </ul>

View on GitHub (pinned to e7288fc434)