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.

You open a URL on your new application and get this:
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:
dev.javahacks.shop.ShopApplication scanned
dev.javahacks.shop.web.HelloController scanned
dev.javahacks.web.HelloController NOT scannedMove 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:
@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:
management.endpoints.web.exposure.include=mappingscurl -s localhost:8080/actuator/mappings | grep -o '"pattern":"[^"]*"' | headIf 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:
server.error.whitelabel.enabled=falsePut 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:
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:
@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 page | Meaning | Where to look |
|---|---|---|
| 404 Not Found | No handler matched | Scan, annotations, path, context path |
| 405 Method Not Allowed | Path matched, HTTP method did not | @GetMapping against the verb used |
| 400 Bad Request | Binding or a missing parameter failed | The log line from DefaultHandlerExceptionResolver |
| 500 Internal Server Error | A handler threw | The stack trace in the log |
| 403 Forbidden | Spring Security rejected it | Security 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:
server.error.include-message=always
server.error.include-stacktrace=on_paramWith 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.


