spring-projects/spring-security · error · AuthenticationCredentialsNotFoundException

Please either configure an AuthenticationConverter or…

Error message

Please either configure an AuthenticationConverter or override attemptAuthentication when extending AbstractAuthenticationProcessingFilter

What it means

AbstractAuthenticationProcessingFilter by default installs a null-object AuthenticationConverter that always throws AuthenticationCredentialsNotFoundException, forcing subclasses to either set an AuthenticationConverter (used by the default attemptAuthentication) or override attemptAuthentication themselves. It is a configuration guard: the filter has no way to extract credentials from the request.

Solutions

Call setAuthenticationConverter(...) with your converter on the filter
Override attemptAuthentication(HttpServletRequest, HttpServletResponse) in your subclass to perform authentication manually
Prefer built-in filters (UsernamePasswordAuthenticationFilter, AuthenticationFilter) which already wire a converter

Example fix

// before
MyAuthFilter f = new MyAuthFilter("/login", authManager);
// after
MyAuthFilter f = new MyAuthFilter("/login", authManager);
f.setAuthenticationConverter(new MyJsonAuthenticationConverter());
// or
@Override
public Authentication attemptAuthentication(HttpServletRequest req, HttpServletResponse res) { ... }

Defensive patterns

Strategy: validation

Validate before calling

AbstractAuthenticationProcessingFilter f = ...;
if (f.getClass().getMethod("attemptAuthentication")
        .getDeclaringClass() == AbstractAuthenticationProcessingFilter.class
    && getConverter(f) == null) {
    throw new IllegalStateException("Filter needs an AuthenticationConverter");
}

Try / catch

try {
    filter.doFilter(request, response, chain);
} catch (AuthenticationCredentialsNotFoundException e) {
    if (e.getMessage().contains("AuthenticationConverter")) {
        log.error("Filter misconfigured: set AuthenticationConverter or override attemptAuthentication");
    }
    throw e;
}

Prevention

Always call setAuthenticationConverter(...) in custom filter constructors
Or override attemptAuthentication in every subclass
Write a smoke test hitting the filter URL at startup

When it happens

Trigger: Instantiating AbstractAuthenticationProcessingFilter (or a subclass that forgot setup, e.g. a plain new AbstractAuthenticationProcessingFilter("/login") with no converter) and receiving a request; specifically UsernamePasswordAuthenticationFilter sets one, but custom subclasses frequently forget.

Common situations: Custom login filters subclassing AbstractAuthenticationProcessingFilter directly without calling setAuthenticationConverter or overriding attemptAuthentication; refactors to newer Spring Security (6.x) where the converter-based default was introduced; JSON login filters built atop the abstract class.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

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

Related errors

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/5a385894bd17dadc. Report an issue: GitHub.

Appendix: source

Thrown at web/src/main/java/org/springframework/security/web/authentication/AbstractAuthenticationProcessingFilter.java:134

 * implementations {@link #setSessionAuthenticationStrategy(SessionAuthenticationStrategy)
 * can be injected} to enable things like session-fixation attack prevention or to control
 * the number of simultaneous sessions a principal may have.
 *
 * @author Ben Alex
 * @author Luke Taylor
 */
public abstract class AbstractAuthenticationProcessingFilter extends GenericFilterBean
		implements ApplicationEventPublisherAware, MessageSourceAware {

	private SecurityContextHolderStrategy securityContextHolderStrategy = SecurityContextHolder
		.getContextHolderStrategy();

	protected @Nullable ApplicationEventPublisher eventPublisher;

	protected AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource = new WebAuthenticationDetailsSource();

	private AuthenticationConverter authenticationConverter = (request) -> {
		throw new AuthenticationCredentialsNotFoundException(
				"Please either configure an AuthenticationConverter or override attemptAuthentication when extending AbstractAuthenticationProcessingFilter");
	};

	@SuppressWarnings("NullAway.Init")
	private AuthenticationManager authenticationManager;

	protected MessageSourceAccessor messages = SpringSecurityMessageSource.getAccessor();

	private RememberMeServices rememberMeServices = new NullRememberMeServices();

	private RequestMatcher requiresAuthenticationRequestMatcher;

	private boolean continueChainBeforeSuccessfulAuthentication = false;

	private boolean continueChainWhenNoAuthenticationResult;

	private SessionAuthenticationStrategy sessionStrategy = new NullAuthenticatedSessionStrategy();

View on GitHub (pinned to 96852e8860)