Whitelabel Error Page (Java) — how to fix
Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.
Sat Nov 21 10:15:42 UTC 2026
There was an unexpected error (type=Not Found, status=404).
Quick fix: Read status= on the page. For 404, check that your controller is in the main class's package or a subpackage, uses @RestController (or @Controller with a real template), and that the URL and HTTP method match the mapping. For 500, look at the stack trace in the console log. Add src/main/resources/templates/error.html or server.error.whitelabel.enabled=false to replace the page.
What it means
When a request fails, Spring Boot forwards it to /error. If you haven't defined a view for that, ErrorMvcAutoConfiguration renders this "whitelabel" HTML page. The page itself is not the bug; the line type=..., status=... is. Turn on more detail while developing:
server.error.include-message=always
server.error.include-stacktrace=on_param
With on_param, add ?trace=true to the URL to see the stack trace.
Cause 1 (404): controller not picked up by component scanning
@SpringBootApplication scans only its own package and subpackages. A controller in a sibling package is never registered:
com.example.demo.DemoApplication <- scans com.example.demo.**
com.example.controller.HelloController <- NOT scanned
Move controllers under com.example.demo (e.g. com.example.demo.web), or widen the scan:
@SpringBootApplication(scanBasePackages = "com.example")
public class DemoApplication { ... }
Check the startup log with logging.level.org.springframework.web=DEBUG: registered mappings are listed.
Cause 2 (404): URL, method or context path doesn't match
@RestController
@RequestMapping("/api")
public class HelloController {
@GetMapping("/hello")
public String hello() { return "hi"; }
}
This answers GET /api/hello only. /hello gives 404; a POST gives 405. If server.servlet.context-path=/app is set, the URL becomes /app/api/hello.
Cause 3 (404 or 500): @Controller returning a view that doesn't exist
With @Controller, a returned string is a template name:
@Controller
public class HomeController {
@GetMapping("/")
public String home() { return "index"; } // needs templates/index.html
}
Without a template engine dependency (spring-boot-starter-thymeleaf) or without src/main/resources/templates/index.html, it fails. If you meant to return text or JSON, use @RestController or add @ResponseBody.
Cause 4 (404 on /): no home page
A new project has no mapping for /. Add a controller, or put a static file at src/main/resources/static/index.html, which Spring Boot serves automatically.
Cause 5 (500): an exception in your code
status=500 means a controller or service threw. The stack trace is in the application log (console), not on the page. Fix the exception, or handle it and return a proper status:
@RestControllerAdvice
public class ApiErrors {
@ExceptionHandler(NoSuchElementException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public Map<String, String> notFound(NoSuchElementException e) {
return Map.of("error", e.getMessage());
}
}
Cause 6 (403/401): Spring Security
With spring-boot-starter-security on the classpath, unauthenticated requests are redirected to /login or rejected, and a 403 can surface as this page (CSRF blocks POST by default). Configure a SecurityFilterChain that permits your routes.
Replace the page
Add a custom template (src/main/resources/templates/error.html, or templates/error/404.html for specific codes; static static/error/404.html works without a template engine), or disable it so the servlet container's default page is used:
server.error.whitelabel.enabled=false
Last updated 2026-11-21.