spring-projects/spring-security · error · IllegalArgumentException

The Filter class {registeredFilter.getName()} does not have

Error message

The Filter class {registeredFilter.getName()} does not have a registered order

What it means

HttpSecurity.addFilterBefore/addFilterAfter/addFilterAt place a custom filter relative to an existing registered filter. If the reference filter class has no known position in HttpSecurity's internal filter-order registry, addFilterAtOffsetOf throws this IllegalArgumentException because an offset cannot be computed.

Source

Thrown at config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java:1833

	private AuthenticationManagerBuilder getAuthenticationRegistry() {
		return getSharedObject(AuthenticationManagerBuilder.class);
	}

	@Override
	public HttpSecurity addFilterAfter(Filter filter, Class<? extends Filter> afterFilter) {
		return addFilterAtOffsetOf(filter, 1, afterFilter);
	}

	@Override
	public HttpSecurity addFilterBefore(Filter filter, Class<? extends Filter> beforeFilter) {
		return addFilterAtOffsetOf(filter, -1, beforeFilter);
	}

	private HttpSecurity addFilterAtOffsetOf(Filter filter, int offset, Class<? extends Filter> registeredFilter) {
		Integer registeredFilterOrder = this.filterOrders.getOrder(registeredFilter);
		if (registeredFilterOrder == null) {
			throw new IllegalArgumentException(
					"The Filter class " + registeredFilter.getName() + " does not have a registered order");
		}
		int order = registeredFilterOrder + offset;
		this.filters.add(new OrderedFilter(filter, order));
		this.filterOrders.put(filter.getClass(), order);
		return this;
	}

	@Override
	public HttpSecurity addFilter(Filter filter) {
		Integer order = this.filterOrders.getOrder(filter.getClass());
		if (order == null) {
			throw new IllegalArgumentException("The Filter class " + filter.getClass().getName()
					+ " does not have a registered order and cannot be added without a specified order. Consider using addFilterBefore or addFilterAfter instead.");
		}
		this.filters.add(new OrderedFilter(filter, order));
		return this;
	}

View on GitHub (pinned to 96852e8860)

Solutions

1. Anchor the placement to a well-known Spring Security filter, e.g. addFilterBefore(f, UsernamePasswordAuthenticationFilter.class)
2. If you must reference a custom filter, first register it with a known order (e.g. addFilterAt with a standard filter, or use FilterComparator-equivalent registration)
3. Use addFilterAt with a built-in filter class when you want to occupy the same slot

Example fix

// before
http.addFilterBefore(myFilter, MyCustomFilter.class);
// after
http.addFilterBefore(myFilter, UsernamePasswordAuthenticationFilter.class);

Class<? extends Filter> anchor = UsernamePasswordAuthenticationFilter.class; // must be a built-in security filter
if (!(java.lang.reflect.Modifier.isPublic(anchor.getModifiers()))) { /* ... */ }
// prefer: only pass classes from org.springframework.security.web.authentication.* etc. as anchors

static boolean isKnownSecurityFilter(Class<? extends Filter> f) {
    return f.getName().startsWith("org.springframework.security.web.");
}

try {
    http.addFilterBefore(myFilter, anchorClass);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("does not have a registered order")) {
        http.addFilterBefore(myFilter, UsernamePasswordAuthenticationFilter.class);
    } else throw e;
}

When it happens

Trigger: Calling http.addFilterBefore(myFilter, SomeFilter.class) where SomeFilter (or the 'after'/'at' target) is not a standard Spring Security filter with a registered order; passing a custom filter class as the reference instead of a built-in one.

Common situations: Using addFilterBefore with another custom filter as the anchor; typos or custom subclasses of security filters whose class differs from the registered one; migrating filters that were never part of the default chain.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The Filter class {filter.getClass().getName()} does not have
• A filter chain that matches any request [{anyRequestFilterCh
• The FilterChainProxy contains two filter chains using the ma
• Possible error: Filters at position <i> and <j> are both ins
• Cannot apply {configurer} to already built object

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