Spring Boot Filters: Servlet Filters, OncePerRequestFilter, and FilterRegistrationBean Explained

In the trenches of Spring Boot 3.2.x, filters are your first line of defense and manipulation for incoming HTTP requests. While Spring Boot auto-configures many filters (like Spring Security's filter chain), you'll inevitably need custom logic—logging, authentication, request mutation, or rate limiting. The Servlet Filter API (javax.servlet/jakarta.servlet) is the bedrock, but Spring wraps it with OncePerRequestFilter to solve a subtle but critical issue: filter execution across multiple dispatch types (forward, include, error, async).

I've seen production outages caused by a filter logging request bodies twice because someone used a plain javax.servlet.Filter with async dispatches. The fix was switching to OncePerRequestFilter, which guarantees single execution per request lifecycle. Then there's FilterRegistrationBean—your escape hatch when auto-configuration fights you. Need to inject a filter before Spring Security's chain? Set order to Ordered.HIGHEST_PRECEDENCE. Want to exclude certain paths? Use setUrlPatterns with exclusion logic.

This article covers the gritty details: when to use each type, how to register them without XML (we're not in 2010), and how to debug filter ordering issues that cause mysterious 401s or double header writes. We'll use real code from a payment-processing system where filter ordering was the difference between a clean audit trail and a compliance nightmare.

Understanding the Servlet Filter Contract in Spring Boot 3.2

The Jakarta Servlet specification defines Filter as an interface with init(), doFilter(), and destroy(). In Spring Boot 3.2 (using Jakarta EE 10), you implement jakarta.servlet.Filter. The doFilter() method receives ServletRequest, ServletResponse, and FilterChain. You must call chain.doFilter() to pass the request downstream; failing to do so hangs the request.

Filters execute in a chain, ordered by their priority. Spring Boot auto-discovers filters as beans and wraps them in a FilterChainProxy. The order is determined by the Ordered interface or @Order annotation. Lower order values run first. Spring Security's FilterChainProxy typically runs at order Ordered.LOWEST_PRECEDENCE - 100, so your custom filters can run before or after by setting appropriate order values.

A critical detail: plain Servlet Filters execute once per dispatch type. If your filter is registered for REQUEST and FORWARD, it runs twice for a single user request that triggers an internal forward. This is where OncePerRequestFilter saves you.

import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.time.Instant;

public class SimpleLoggingFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        System.out.println("Filter executed at " + Instant.now() +
                           " for " + req.getMethod() + " " + req.getRequestURI());
        chain.doFilter(request, response);
        System.out.println("Filter completed for " + req.getMethod());
    }

    @Override
    public void init(FilterConfig filterConfig) {}

    @Override
    public void destroy() {}
}

What the Official Docs Won't Tell You

Spring's official documentation glosses over a painful truth: OncePerRequestFilter is not thread-safe by default. The base class uses an attribute on the request to track execution, but if you store mutable state in the filter instance itself (e.g., a counter or a cached object), you'll get race conditions under load. I debugged a case where a filter mutated a shared HashMap to track request IDs—within minutes under 500 req/s, we saw ConcurrentModificationException and corrupted data.

Another undocumented behavior: OncePerRequestFilter skips execution for ERROR dispatches by default. That means if your controller throws an exception and Spring's error page mechanism kicks in, the filter won't run again. This is usually desired, but if you need to log errors, you must override shouldNotFilterErrorDispatch() to return false.

Finally, FilterRegistrationBean's setUrlPatterns() accepts Ant-style patterns but does NOT support regex. Many developers try "/api/v[0-9]+/.*" and wonder why it fails. Use Ant patterns like "/api/v1/" or "/api/v2/" explicitly.

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.concurrent.atomic.AtomicLong;

public class SafeOncePerRequestFilter extends OncePerRequestFilter {

    // Use AtomicLong for thread-safe counters; never use plain long
    private final AtomicLong requestCounter = new AtomicLong(0);

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {
        long requestId = requestCounter.incrementAndGet();
        request.setAttribute("requestId", requestId);
        // Log or process
        filterChain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilterErrorDispatch() {
        // Return false if you want this filter to run on error dispatches
        return false;
    }
}

Registering Filters with FilterRegistrationBean

Before Spring Boot, you configured filters in web.xml. Now, you use FilterRegistrationBean in a @Configuration class. This gives you explicit control over URL patterns, servlet names, and order. Without it, Spring Boot auto-registers filter beans with default patterns (/*) and arbitrary order based on bean creation time.

FilterRegistrationBean accepts a Filter instance, setUrlPatterns(), setServletNames(), and setOrder(). The order is crucial: lower values run first. Spring Security's filter chain has order Ordered.LOWEST_PRECEDENCE - 100 (usually around Integer.MAX_VALUE - 100). To run before security, use order = Ordered.HIGHEST_PRECEDENCE (Integer.MIN_VALUE). To run after security, use order = Ordered.LOWEST_PRECEDENCE.

One pattern I use in every project: create a dedicated configuration class for filter registration. This avoids scattering bean definitions across multiple files. Also, use setDispatcherTypes() to specify which dispatches the filter applies to. By default, it's only REQUEST. Add FORWARD, ERROR, or ASYNC as needed.

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;

@Configuration
public class FilterConfig {

    @Bean
    public FilterRegistrationBean<RequestLoggingFilter> loggingFilter() {
        FilterRegistrationBean<RequestLoggingFilter> registrationBean =
                new FilterRegistrationBean<>();
        registrationBean.setFilter(new RequestLoggingFilter());
        registrationBean.addUrlPatterns("/api/*");
        registrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE); // Run first
        return registrationBean;
    }

    @Bean
    public FilterRegistrationBean<AuthFilter> authFilter() {
        FilterRegistrationBean<AuthFilter> registrationBean =
                new FilterRegistrationBean<>();
        registrationBean.setFilter(new AuthFilter());
        registrationBean.addUrlPatterns("/api/secure/*");
        registrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE + 1); // Run after logging
        return registrationBean;
    }
}

OncePerRequestFilter: The Single-Execution Guarantee

OncePerRequestFilter is an abstract class in Spring that wraps a Servlet Filter and ensures doFilterInternal() is called only once per request dispatch cycle. It uses a request attribute ("org.springframework.web.filter.OncePerRequestFilter") to track execution. If you call chain.doFilter() and the request is forwarded, the filter checks the attribute and skips execution.

This is essential for filters that modify the response (like adding headers) or perform side effects (like logging). Without it, a forward would cause duplicate headers or double log entries. Spring Security's filters are all OncePerRequestFilter for this reason.

To implement, extend OncePerRequestFilter and override doFilterInternal(). You get HttpServletRequest and HttpServletResponse directly—no casting needed. You can also override shouldNotFilter() to skip certain requests based on path or method. Common use cases: adding correlation IDs, validating API keys, rate limiting, and response compression.

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.UUID;

public class CorrelationIdFilter extends OncePerRequestFilter {

    private static final String CORRELATION_ID_HEADER = "X-Correlation-Id";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {
        String correlationId = request.getHeader(CORRELATION_ID_HEADER);
        if (correlationId == null || correlationId.isEmpty()) {
            correlationId = UUID.randomUUID().toString();
        }
        response.setHeader(CORRELATION_ID_HEADER, correlationId);
        // Optionally set as request attribute for downstream use
        request.setAttribute(CORRELATION_ID_HEADER, correlationId);
        filterChain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        String path = request.getRequestURI();
        return path.startsWith("/actuator"); // Skip health checks
    }
}

Filter Ordering: The Silent Killer in Production

Filter ordering is deceptively simple until it breaks. Spring Boot's auto-configuration registers filters in an order that depends on bean creation order, which is non-deterministic across restarts. I've seen a filter that set a request attribute run after a filter that read that attribute, causing NullPointerException in production.

The rule: always use FilterRegistrationBean with explicit setOrder(). Use constants from Ordered interface or define your own. Common patterns: - Ordered.HIGHEST_PRECEDENCE: For filters that must run before everything (e.g., tenant resolution, correlation ID). - Ordered.HIGHEST_PRECEDENCE + 100: For authentication/authorization filters. - Ordered.LOWEST_PRECEDENCE: For response-wrapping filters (e.g., compression, response logging).

Spring Security uses its own filter chain, which is a single filter in the servlet container's chain. Your custom filters can run before or after the security chain by setting order relative to SecurityProperties.DEFAULT_FILTER_ORDER (which is Ordered.LOWEST_PRECEDENCE - 100).

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.security.config.annotation.web.configuration.WebSecurityCustomizer;

@Configuration
public class OrderedFiltersConfig {

    @Bean
    public FilterRegistrationBean<TenantFilter> tenantFilter() {
        FilterRegistrationBean<TenantFilter> bean = new FilterRegistrationBean<>();
        bean.setFilter(new TenantFilter());
        bean.addUrlPatterns("/api/*");
        bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
        return bean;
    }

    @Bean
    public FilterRegistrationBean<AuthFilter> authFilter() {
        FilterRegistrationBean<AuthFilter> bean = new FilterRegistrationBean<>();
        bean.setFilter(new AuthFilter());
        bean.addUrlPatterns("/api/secure/*");
        // Run after tenant filter but before Spring Security
        bean.setOrder(Ordered.HIGHEST_PRECEDENCE + 100);
        return bean;
    }

    @Bean
    public WebSecurityCustomizer webSecurityCustomizer() {
        return (web) -> web.ignoring().requestMatchers("/api/public/**");
    }
}

Advanced: Async Dispatch and Filter Execution

Spring Boot supports async request processing via DeferredResult or Callable. With async, the request thread is released, and the response is written later by a worker thread. Filters must handle ASYNC dispatches correctly. By default, OncePerRequestFilter does NOT run on ASYNC dispatches (shouldNotFilterAsyncDispatch() returns true). This is usually correct because you don't want to log or modify the response twice.

However, if your filter sets response headers that must be present on async responses (e.g., CORS headers), you need to override shouldNotFilterAsyncDispatch() to return false. But beware: the filter will execute on both the initial REQUEST dispatch and the ASYNC dispatch. You must ensure your filter logic is idempotent.

For plain Servlet Filters, you must register them with ASYNC dispatcher type via FilterRegistrationBean.setDispatcherTypes(DispatcherType.REQUEST, DispatcherType.ASYNC). Otherwise, they won't execute on async completions.

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

public class AsyncAwareFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {
        // Set header only on initial dispatch, not on async dispatch
        if (!request.isAsyncStarted()) {
            response.setHeader("X-Processed-By", "filter-v1");
        }
        filterChain.doFilter(request, response);
    }

    @Override
    protected boolean shouldNotFilterAsyncDispatch() {
        return true; // Don't run on async dispatch (default)
    }
}

Testing Filters: Beyond Unit Tests

Unit testing a filter in isolation tells you nothing about ordering or dispatch type behavior. You need integration tests with MockMvc or TestRestTemplate. Use @WebMvcTest with your filters explicitly registered, or @SpringBootTest with a random port.

Key things to test: filter executes for expected paths, filter does NOT execute for excluded paths, filter sets correct headers/attributes, filter handles exceptions gracefully (should not swallow exceptions), and filter works with async dispatches.

Use MockHttpServletRequest and MockHttpServletResponse for unit tests of doFilterInternal(). But for ordering tests, use @SpringBootTest and inspect the FilterChainProxy bean.

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;

import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(controllers = SomeController.class)
public class FilterIntegrationTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void correlationIdFilter_shouldAddHeader() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.get("/api/orders"))
               .andExpect(status().isOk())
               .andExpect(header().exists("X-Correlation-Id"));
    }

    @Test
    void correlationIdFilter_shouldSkipActuator() throws Exception {
        mockMvc.perform(MockMvcRequestBuilders.get("/actuator/health"))
               .andExpect(status().isOk())
               .andExpect(header().doesNotExist("X-Correlation-Id"));
    }
}

Production Debugging: Filter Not Executing?

When a filter mysteriously doesn't execute, the cause is almost always one of these: wrong URL pattern, wrong order (another filter short-circuits the chain), or the filter is not registered as a bean. Use Spring Boot's actuator endpoints to inspect registered filters. Enable debug logging for org.springframework.boot.web.servlet.FilterRegistrationBean to see which filters are registered.

Another common issue: the filter throws an exception before calling chain.doFilter(), and the exception is swallowed by a parent filter (like Spring Security's ExceptionTranslationFilter). Always log exceptions in your filter's doFilterInternal().

Finally, if you're using Spring Security, your custom filter might be running inside the security filter chain, not the servlet container chain. To add a filter to the security chain, use HttpSecurity.addFilterBefore() or addFilterAfter(). This is different from FilterRegistrationBean.

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class DebugFilterConfig {

    @Bean
    public FilterRegistrationBean<DebugFilter> debugFilter() {
        FilterRegistrationBean<DebugFilter> bean = new FilterRegistrationBean<>();
        bean.setFilter(new DebugFilter());
        bean.addUrlPatterns("/api/*");
        bean.setOrder(1);
        // Enable debug logging in application.properties:
        // logging.level.org.springframework.boot.web.servlet.FilterRegistrationBean=DEBUG
        return bean;
    }
}