Skip to content
javahacks.dev
Spring Boot

Fix Spring Boot Whitelabel Error Page 404 Not Found Errors

Fix the Whitelabel Error Page in Spring Boot by checking component scanning, the mapped path, the context path and the template location.

5 min read
Summarize in AI
Flat illustration of a start button surrounded by Spring Boot starters, with the Spring Boot, Spring, Spring Security and Docker logos.

You open a URL on your new application and get this:

Text
Whitelabel Error Page

This application has no explicit mapping for /error, so you are seeing this as a fallback.

There was an unexpected error (type=Not Found, status=404).

Spring MVC tried to find something to handle your request, found nothing and fell back to the error page. The page itself is not the problem; it is the symptom of a missing mapping. The checks below go from most to least likely. The request path is explained in how Spring MVC handles a request, and the project layout in Spring Boot from first project to production.

Cause 1: the controller is not scanned

@SpringBootApplication scans its own package and everything below. A controller in a different root package is invisible:

Text
dev.javahacks.shop.ShopApplication          scanned
dev.javahacks.shop.web.HelloController      scanned
dev.javahacks.web.HelloController           NOT scanned

Move the class under the application package, or widen the scan with @SpringBootApplication(scanBasePackages = "dev.javahacks"). Moving is better, because the scan then matches the structure.

Cause 2: the annotation is missing

A class needs @RestController (or @Controller for views) to become a handler:

java
@RestController
class HelloController {

    @GetMapping("/hello")
    String hello() {
        return "hello";
    }
}

A plain class with @RequestMapping methods and no stereotype is not registered. Also check imports: @GetMapping must come from org.springframework.web.bind.annotation.

Cause 3: the path is not the one you typed

Check server.servlet.context-path and any class-level @RequestMapping. With server.servlet.context-path=/app and @RequestMapping("/api") on the class, the full URL is /app/api/hello. A trailing slash is not matched by default in Spring Framework 6 and later, so /hello/ is a different URL from /hello.

Cause 4: a view or a static file is in the wrong place

Static files belong in src/main/resources/static, and Thymeleaf templates in src/main/resources/templates. A file in src/main/webapp is ignored in a jar. A controller that returns a view name home needs templates/home.html; a missing template usually gives a 500, not a 404, but the path to the controller can still 404 if the controller itself is not found.

Prove it with the mappings endpoint

Add Actuator, expose the endpoint and read the list:

properties
management.endpoints.web.exposure.include=mappings
Shell
curl -s localhost:8080/actuator/mappings | grep -o '"pattern":"[^"]*"' | head

If your path is not in the list, the controller was not registered, which is cause 1 or 2. If it is in the list, you are requesting a different URL. Remove the exposure setting when you are done.

Customize the page for production

The Whitelabel page leaks that you are running Spring Boot, and a browser user gets nothing useful. Turn it off and provide your own:

properties
server.error.whitelabel.enabled=false

Put an error.html template under templates/ for HTML clients. For a JSON API, return problem details from a @RestControllerAdvice, as in building REST APIs with Spring MVC.

Cause 5: the web starter is missing or the wrong one is on the classpath

A project that has spring-boot-starter-web has Spring MVC. One that has only spring-boot-starter-webflux runs the reactive stack, which also supports annotated controllers but handles static files and templates differently. A project with both runs MVC unless the application type is set. If a controller works in one project and 404s in another that looks identical, compare ./mvnw dependency:tree | grep starter between them, and check the startup log for the line naming the embedded server and the stack.

Cause 6: static content is disabled or mapped elsewhere

Boot serves static/, public/, resources/ and META-INF/resources/ from the classpath at the root of the context. Two settings change that:

properties
spring.web.resources.add-mappings=false
spring.mvc.static-path-pattern=/assets/**

The first turns static serving off completely, so index.html stops being the welcome page. The second moves it, so a file at static/logo.png is now at /assets/logo.png. A @EnableWebMvc annotation on any configuration class switches off Boot's MVC auto-configuration altogether, and the usual symptom is the Whitelabel page for a URL that used to serve a file.

A test that catches the missing mapping

A 404 found in the browser can be found in the build. A slice test loads only the web layer and asserts the route exists:

java
@WebMvcTest(HelloController.class)
class HelloControllerTest {

    @Autowired
    MockMvc mvc;

    @Test
    void helloIsMapped() throws Exception {
        mvc.perform(get("/hello"))
           .andExpect(status().isOk())
           .andExpect(content().string("hello"));
    }
}

If the controller is not scanned or the path is wrong, the test fails with Status expected:<200> but was:<404>. Run it before the first deploy and the page never reaches a user. For the full application context, @SpringBootTest with @AutoConfigureMockMvc gives the same assertion with security and filters included.

Reading the page's status line

The Whitelabel page prints a type and a status, and the status separates the causes.

Status on the pageMeaningWhere to look
404 Not FoundNo handler matchedScan, annotations, path, context path
405 Method Not AllowedPath matched, HTTP method did not@GetMapping against the verb used
400 Bad RequestBinding or a missing parameter failedThe log line from DefaultHandlerExceptionResolver
500 Internal Server ErrorA handler threwThe stack trace in the log
403 ForbiddenSpring Security rejected itSecurity configuration, CSRF on a POST

A 405 deserves its own mention, because it is the one that makes a correct path look wrong. A form that submits a POST to a @GetMapping handler produces a Whitelabel page with Method Not Allowed, and nothing on it mentions the verb unless the message is shown.

Show a reason during development

By default the error attributes hide the message and the trace. For local work, turn them on and turn them off again before release:

properties
server.error.include-message=always
server.error.include-stacktrace=on_param

With on_param, appending ?trace=true to a URL includes the trace, so it is available on demand without being the default. Do not enable always on a public service, because a trace discloses class names, library versions and sometimes SQL.

DevTools and stale classes

A controller added while DevTools is running is picked up by the restart classloader, and a controller moved to a new package may not be. If the mappings endpoint is missing a handler that is plainly in the source, stop the application and start it again from a clean build. The same applies to a template that was added after the jar was built, because the running jar cannot see files that were not packaged into it.

Where this does not apply

A 404 from a reverse proxy or an ingress shows the proxy's page, not the Whitelabel one. If you see the Whitelabel page with status 500, the cause is an exception, not a missing route, so read the log. The Spring Boot web reference documents the error handling properties. The Spring Boot how-to guides documents the behavior in detail.

Also inSpring MVC
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.