Introduction

When a Spring Boot interceptor is never called, the problem is usually configuration rather than interceptor logic. The interceptor class may not be a bean, it may not be registered with Spring MVC, or the application may not be using the MVC stack that interceptors depend on.

A Minimal Working Setup

For a standard Spring MVC application, the interceptor should be a bean and must be added through WebMvcConfigurer.

1package com.example.demo;
2
3import jakarta.servlet.http.HttpServletRequest;
4import jakarta.servlet.http.HttpServletResponse;
5import org.springframework.stereotype.Component;
6import org.springframework.web.servlet.HandlerInterceptor;
7
8@Component
9public class LoggingInterceptor implements HandlerInterceptor {
10    @Override
11    public boolean preHandle(HttpServletRequest request,
12                             HttpServletResponse response,
13                             Object handler) {
14        System.out.println("Intercepted: " + request.getRequestURI());
15        return true;
16    }
17}

Then register it:

1package com.example.demo;
2
3import org.springframework.beans.factory.annotation.Autowired;
4import org.springframework.context.annotation.Configuration;
5import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
6import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
7
8@Configuration
9public class WebConfig implements WebMvcConfigurer {
10
11    @Autowired
12    private LoggingInterceptor loggingInterceptor;
13
14    @Override
15    public void addInterceptors(InterceptorRegistry registry) {
16        registry.addInterceptor(loggingInterceptor)
17                .addPathPatterns("/**")
18                .excludePathPatterns("/error");
19    }
20}

If this configuration is in a package scanned by @SpringBootApplication, requests should pass through preHandle().

Why Interceptors Often Fail to Start

The first common failure is that the interceptor class is not a Spring bean. If it lacks @Component and is not declared in a @Bean method, the application cannot inject and register it.

The second failure is package scanning. Spring Boot scans from the package of the main application class downward. If your interceptor or config class lives outside that tree, it may never be discovered.

The third issue is assuming a HandlerInterceptor will run in Spring WebFlux. It will not. WebFlux uses WebFilter and related reactive mechanisms instead of MVC interceptors.

Path Patterns and Exclusions

Sometimes the interceptor is registered correctly but still appears unused because the request path does not match the configured patterns.

registry.addInterceptor(loggingInterceptor)
        .addPathPatterns("/api/**")
        .excludePathPatterns("/api/health");

If you test /login while the interceptor only covers /api/**, nothing is wrong with initialization. The path rules simply do not match.

Static resources can also bypass the paths you care about, which makes manual testing misleading if you are not hitting an actual controller route.

Avoid Overriding MVC Auto-Configuration Accidentally

Spring Boot's MVC auto-configuration is helpful, but it can be disabled unintentionally. Extending WebMvcConfigurationSupport or using @EnableWebMvc changes how the framework is configured and can introduce surprises if done without a strong reason.

In most Boot applications, implementing WebMvcConfigurer is enough. It augments the default MVC configuration instead of replacing it.

Debugging the Problem

A quick way to debug is to set a breakpoint in addInterceptors() and in preHandle(). If addInterceptors() never runs, your config class is probably not being loaded. If registration happens but preHandle() never runs, inspect path matching and whether the request is going through Spring MVC at all.

You can also add a trivial controller for testing:

1package com.example.demo;
2
3import org.springframework.web.bind.annotation.GetMapping;
4import org.springframework.web.bind.annotation.RestController;
5
6@RestController
7public class DemoController {
8    @GetMapping("/ping")
9    public String ping() {
10        return "pong";
11    }
12}

Hitting /ping gives you a predictable route to verify the interceptor chain.

Common Pitfalls

A common mistake is creating the interceptor with new LoggingInterceptor() inside the config class while also expecting dependency injection inside the interceptor. If the interceptor needs Spring-managed collaborators, let Spring create it as a bean.

Another issue is mixing MVC and WebFlux concepts. A HandlerInterceptor will not intercept reactive routes in a WebFlux application.

Developers also sometimes place configuration classes outside the scanned package structure. Spring then starts normally, but the interceptor bean and registration class are never loaded.

Summary

• Make the interceptor a Spring bean and register it through WebMvcConfigurer.
• Ensure both the interceptor and config classes are inside component-scanned packages.
• Verify your path patterns actually match the requests you are testing.
• Use MVC interceptors only in Spring MVC, not WebFlux.
• Prefer WebMvcConfigurer over replacing Boot's MVC setup unless you need full control.