javaspring-boottomcaterror-handling

How to override default Tomcat 404 not found html page in Spring Boot 3.2?


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:

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!


Solution

  • 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);
                }
            });
        }
    }