The Spring Boot's WelcomePageHandlerMapping is getting called on invalid API path where the 404 error expected

Question

I have a simple Spring Boot (3.1.2) application with defined @RestController with several @GetMapping (/app/test, /app/test2).

E.g:

@GetMapping("/test")
    public TestModel getTestModel() {
        return TestModel.builder()
                .testModelName("The best test model ever!")
                .testModelVersion(1)
                .build();
    }

So when I'm trying to send a request to my app using the incorrect API path and Accept header like this:

curl -X GET http://localhost:8080/random/incorrect -H "Accept: yaml"

Instead of expected 404 Not Found error, I'm getting this exception:

jakarta.servlet.ServletException: Request processing failed: org.springframework.http.InvalidMediaTypeException: Invalid mime type "yaml": does not contain '/'
    at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1019) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:903) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:500) ~[jakarta.servlet-api-5.0.0.jar:5.0.0]
    at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:885) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:587) ~[jakarta.servlet-api-5.0.0.jar:5.0.0]
    at org.eclipse.jetty.servlet.ServletHolder.handle(ServletHolder.java:764) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler$ChainEnd.doFilter(ServletHandler.java:1665) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100) ~[spring-web-6.0.11.jar:6.0.11]
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116) ~[spring-web-6.0.11.jar:6.0.11]
    at org.eclipse.jetty.servlet.FilterHolder.doFilter(FilterHolder.java:202) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler$Chain.doFilter(ServletHandler.java:1635) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93) ~[spring-web-6.0.11.jar:6.0.11]
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116) ~[spring-web-6.0.11.jar:6.0.11]
    at org.eclipse.jetty.servlet.FilterHolder.doFilter(FilterHolder.java:202) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler$Chain.doFilter(ServletHandler.java:1635) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201) ~[spring-web-6.0.11.jar:6.0.11]
    at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116) ~[spring-web-6.0.11.jar:6.0.11]
    at org.eclipse.jetty.servlet.FilterHolder.doFilter(FilterHolder.java:202) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler$Chain.doFilter(ServletHandler.java:1635) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.websocket.servlet.WebSocketUpgradeFilter.doFilter(WebSocketUpgradeFilter.java:170) ~[websocket-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.FilterHolder.doFilter(FilterHolder.java:202) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler$Chain.doFilter(ServletHandler.java:1635) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler.doHandle(ServletHandler.java:527) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ScopedHandler.handle(ScopedHandler.java:131) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.security.SecurityHandler.handle(SecurityHandler.java:578) ~[jetty-security-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.HandlerWrapper.handle(HandlerWrapper.java:122) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ScopedHandler.nextHandle(ScopedHandler.java:223) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.session.SessionHandler.doHandle(SessionHandler.java:1570) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ScopedHandler.nextHandle(ScopedHandler.java:221) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ContextHandler.doHandle(ContextHandler.java:1381) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ScopedHandler.nextScope(ScopedHandler.java:176) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.servlet.ServletHandler.doScope(ServletHandler.java:484) ~[jetty-servlet-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.session.SessionHandler.doScope(SessionHandler.java:1543) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ScopedHandler.nextScope(ScopedHandler.java:174) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ContextHandler.doScope(ContextHandler.java:1303) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.ScopedHandler.handle(ScopedHandler.java:129) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.handler.HandlerWrapper.handle(HandlerWrapper.java:122) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.Server.handle(Server.java:563) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.HttpChannel.lambda$handle$0(HttpChannel.java:505) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.HttpChannel.dispatch(HttpChannel.java:762) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.HttpChannel.handle(HttpChannel.java:497) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.server.HttpConnection.onFillable(HttpConnection.java:282) ~[jetty-server-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.io.AbstractConnection$ReadCallback.succeeded(AbstractConnection.java:314) ~[jetty-io-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.io.FillInterest.fillable(FillInterest.java:100) ~[jetty-io-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.io.SelectableChannelEndPoint$1.run(SelectableChannelEndPoint.java:53) ~[jetty-io-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:969) ~[jetty-util-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.util.thread.QueuedThreadPool$Runner.doRunJob(QueuedThreadPool.java:1194) ~[jetty-util-11.0.15.jar:11.0.15]
    at org.eclipse.jetty.util.thread.QueuedThreadPool$Runner.run(QueuedThreadPool.java:1149) ~[jetty-util-11.0.15.jar:11.0.15]
    at java.base/java.lang.Thread.run(Thread.java:833) ~[na:na]
Caused by: org.springframework.http.InvalidMediaTypeException: Invalid mime type "yaml": does not contain '/'
    at org.springframework.http.MediaType.parseMediaType(MediaType.java:742) ~[spring-web-6.0.11.jar:6.0.11]
    at org.springframework.http.MediaType.parseMediaTypes(MediaType.java:768) ~[spring-web-6.0.11.jar:6.0.11]
    at org.springframework.boot.autoconfigure.web.servlet.WelcomePageHandlerMapping.getAcceptedMediaTypes(WelcomePageHandlerMapping.java:82) ~[spring-boot-autoconfigure-3.1.2.jar:3.1.2]
    at org.springframework.boot.autoconfigure.web.servlet.WelcomePageHandlerMapping.isHtmlTextAccepted(WelcomePageHandlerMapping.java:71) ~[spring-boot-autoconfigure-3.1.2.jar:3.1.2]
    at org.springframework.boot.autoconfigure.web.servlet.WelcomePageHandlerMapping.getHandlerInternal(WelcomePageHandlerMapping.java:67) ~[spring-boot-autoconfigure-3.1.2.jar:3.1.2]
    at org.springframework.web.servlet.handler.AbstractHandlerMapping.getHandler(AbstractHandlerMapping.java:505) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at org.springframework.web.servlet.DispatcherServlet.getHandler(DispatcherServlet.java:1275) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1057) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:974) ~[spring-webmvc-6.0.11.jar:6.0.11]
    at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1011) ~[spring-webmvc-6.0.11.jar:6.0.11]
    ... 48 common frames omitted

As I can see the WelcomePageHandlerMapping is getting called. So my question is: why is this handler getting called instead of returning the 404 error instantly?

I tried to find some info in documentation but I had no luck.

Answer 1

When a request is received, Spring MVC calls all registered handler mappings in order until one provides a handler for the request.

WelcomePageHandlerMapping is ordered after the RequestMappingHandlerMapping so WelcomePageHandlerMapping will only be called if no @RequestMapping matches the request.

When WelcomePageHandlerMapping is called it has to determine if it can provide a handler for the incoming request. Part of determining if it can do so is checking to see if the request will accept a text/html response. This check is done before checking that the path matches so the invalid Accept header causes a problem irrespective of the request's path.