I'm working on a Spring Boot 3.2 (Apache Tomcat 10) application and have set a custom context path (/api). I want to replace the default HTML error responses from Tomcat with JSON/status-only responses. However, I am encountering difficulties handling 404 errors that occur outside of the context path - on a bare base URL, for example. I get this:
...
<body>
<h1>HTTP Status 404 – Not Found</h1>
<hr class="line" />
<p><b>Type</b> Status Report</p>
<p><b>Description</b> The origin server did not find a current representation for the target resource or is not
willing to disclose that one exists.</p>
<hr class="line" />
<h3>Apache Tomcat/10.1.19</h3>
</body>
...
My configs:
Global Exception Handler
@Slf4j
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity<?> handleGlobalException(Exception ex) {
log.error("An error occurred: {}", ex.getMessage(), ex);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(new ApiResponse(false, ex.getMessage()));
}
@ExceptionHandler(NoResourceFoundException.class)
public ResponseEntity<?> handleNoResourceFoundException(NoResourceFoundException ignored) {
return new ResponseEntity<>(HttpStatus.NOT_FOUND);
}
}
Security Configuration
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
return http.csrf(AbstractHttpConfigurer::disable)
.cors(Customizer.withDefaults())
.exceptionHandling(exception ->
exception.authenticationEntryPoint(new HttpStatusEntryPoint(HttpStatus.NOT_FOUND)))
.authorizeHttpRequests(auth -> auth.requestMatchers(PERMIT_ALL_URL_PATTERNS.toArray(new String[0]))
.permitAll()
.anyRequest()
.authenticated())
.sessionManagement(manager -> manager.sessionCreationPolicy(STATELESS))
.formLogin(AbstractHttpConfigurer::disable)
.httpBasic(AbstractHttpConfigurer::disable)
.oauth2Login(loginConfigurer -> loginConfigurer
.userInfoEndpoint(endpointConfig -> endpointConfig.userService(customOAuth2UserService))
.successHandler(oAuth2AuthenticationSuccessHandler)
.authorizationEndpoint(authEndPoint ->
authEndPoint.authorizationRequestRepository(authorizationRequestRepository))
.failureHandler(oAuth2AuthenticationFailureHandler))
.build();
}
Observed Issues:
What I tried:
spring.mvc.throw-exception-if-no-handler-found - it's deprecated, IIUC NoHandlerFoundException is no longer thrown in new Spring Boot versions.error.whitelabel.enabled=false - useless for me, since all errors that can happen in my application are handled with a global exception handler anyway.CustomErrorController
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;
@Controller
public class CustomErrorController implements ErrorController {
@RequestMapping("/error")
public ResponseEntity<Map<String, String>> handleError(HttpServletRequest request) {
Object status = request.getAttribute("javax.servlet.error.status_code");
HttpStatus httpStatus = HttpStatus.valueOf(Integer.parseInt(status.toString()));
Map<String, String> response = new HashMap<>();
response.put("error", httpStatus.getReasonPhrase());
response.put("message", "The requested URL was not found on this server.");
return new ResponseEntity<>(response, httpStatus);
}
@Override
public String getErrorPath() {
return "/error";
}
}
Custom ErrorReportValve
@Slf4j
public class CustomTomcatErrorValve extends ErrorReportValve {
@Override
protected void report(Request request, Response response, Throwable throwable) {
if (!response.setErrorReported()) return;
if (log.isDebugEnabled())
log.debug(
"Tomcat failed to prepare the request for spring (set response code to {}).",
response.getStatus(),
throwable);
HttpStatus status = HttpStatus.valueOf(response.getStatus());
try {
response.setContentType("application/problem+json");
Writer writer = response.getReporter();
writer.write(String.format(
"""
{
"title": "%s",
"status": %d
}""",
status.getReasonPhrase(), status.value()));
response.finishResponse();
} catch (IOException ignored) {
}
}
}
Exception handler filter:
@Slf4j
@Component
public class UnhandledExceptionHandlerFilter extends OncePerRequestFilter {
private static class StatusCodeCaptureWrapper extends HttpServletResponseWrapper {
@Getter
private Integer statusCode;
@Getter
private final HttpServletRequest request;
@Getter
private final HttpServletResponse response;
public StatusCodeCaptureWrapper(HttpServletRequest request, HttpServletResponse response) {
super(response);
this.request = request;
this.response = response;
}
}
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
throws IOException {
StatusCodeCaptureWrapper responseWrapper = new StatusCodeCaptureWrapper(request, response);
Throwable exception = null;
try {
chain.doFilter(request, responseWrapper);
} catch (ServletException e) {
exception = e.getRootCause();
} catch (Throwable e) {
exception = e;
}
if (exception != null
&& !"ClientAbortException".equals(exception.getClass().getSimpleName())) {
ensureErrorStatusCodeSet(responseWrapper);
response.setStatus(responseWrapper.getStatusCode());
handleException(request, response, responseWrapper.getStatusCode(), exception);
}
response.flushBuffer();
}
private void ensureErrorStatusCodeSet(StatusCodeCaptureWrapper responseWrapper) {
if (responseWrapper.getStatusCode() == null) {
responseWrapper.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
}
}
private void handleException(
HttpServletRequest request, HttpServletResponse response, int statusCode, Throwable throwable)
throws IOException {
log.error("Sending error response status {} for {} because of", statusCode, request.getRequestURI(), throwable);
response.setContentType("application/json");
response.setCharacterEncoding("UTF-8");
Map<String, String> responseBody = new HashMap<>();
responseBody.put("error", HttpStatus.valueOf(statusCode).getReasonPhrase());
responseBody.put("message", throwable.getMessage());
response.getWriter().write(new ObjectMapper().writeValueAsString(responseBody));
}
}
How can I configure Spring Boot 3.2 to always return JSON error responses, especially for 404 errors, instead of Tomcat's default HTML error pages, even for URLs outside of the context path?
Any guidance or solutions would be greatly appreciated!
This configuration worked for me - we need two classes, CustomTomcatErrorValve and TomcatConfig
CustomTomcatErrorValve.java
@Slf4j
public class CustomTomcatErrorValve extends ErrorReportValve {
@Override
protected void report(Request request, Response response, Throwable throwable) {
if (!response.setErrorReported()) {
return;
}
int statusCode = response.getStatus();
String reasonPhrase = HttpStatus.valueOf(statusCode).getReasonPhrase();
try {
response.setContentType(MediaType.APPLICATION_JSON_VALUE);
response.setCharacterEncoding(StandardCharsets.UTF_8.name());
String jsonResponse = String.format("""
{
"title": "%s",
"status": %d
}
""", reasonPhrase, statusCode);
response.getWriter().write(jsonResponse);
response.getWriter().flush();
log.error("Error reported: {} {} - URI: {}", statusCode, reasonPhrase, request.getRequestURI(), throwable);
} catch (IOException e) {
log.error("Failed to write custom error response", e);
}
}
}
TomcatConfig.java
@Configuration
public class TomcatConfig {
@Bean
public WebServerFactoryCustomizer<TomcatServletWebServerFactory> tomcatCustomizer() {
return factory -> factory.addContextCustomizers(context -> {
try {
StandardHost host = (StandardHost) context.getParent();
host.setErrorReportValveClass(CustomTomcatErrorValve.class.getName());
} catch (Exception e) {
throw new RuntimeException("Failed to set custom ErrorReportValve", e);
}
});
}
}