The annotation @ExceptionHandler is used on a controller's methods that are not themselves handler methods, i.e. methods that are not already annotated with @RequestMapping (or its variants like @GetMappin) .
@ExceptionHandler can be used to return custom error response content to the caller.
Definition of ExceptionHandlerVersion: 7.0.6 package org.springframework.web.bind.annotation;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Reflective(ExceptionHandlerReflectiveProcessor.class)
public @interface ExceptionHandler {
@AliasFor("exception")
Class<? extends Throwable>[] value() default {}; 1
@AliasFor("value")
Class<? extends Throwable>[] exception() default {}; 2
String[] produces() default {}; 3
}
Understanding @ExceptionHandler
Following are the important things to know about this annotation:
- The value element
The 'value' element (aliased by 'exception' since Spring Framework 6.2 — the two are interchangeable) is for specifying the exception type(s) handled by the method. If an exception is thrown, then the annotated method will only be invoked when it matches the 'value'/'exception' type. The match is done based on the most specialized type, for example if:
- method A has specified: @ExceptionHandler(RuntimeException.class)
- and method B has specified: @ExceptionHandler(Exception.class)
- a handler method throws RuntimeException, then A will be invoked.
- if method A doesn't exist, then the thrown RuntimeException will instead match method B, because Exception is the superclass of RuntimeException.
- The produces element
The 'produces' element (also since Spring Framework 6.2) lets you restrict an exception handler method to requests that ask for a specific media type (via the Accept header), which is useful when multiple @ExceptionHandler methods can match the same exception type but should return different content types.
- The parameters
Methods annotated with this annotation are allowed to have very flexible signatures. They may take an exception argument (either the general Exception type or a more specific one), and this argument also serves as a matching hint when the annotation's 'value'/'exception' element is empty. The exception argument can refer to a top-level exception being propagated or to a nested cause inside a wrapper exception — any level of the cause chain can be matched, not just the outermost exception. Handler methods can additionally take request/response objects, the current HttpSession, WebRequest/NativeWebRequest, the current Locale, raw InputStream/OutputStream (or Reader/Writer), and a Model parameter — though the Model passed to an exception handler is always empty, since it isn't pre-populated with regular model attributes.
Check out the complete list of parameter and return types here.
- When value/exception is empty
If @ExceptionHandler's 'value'/'exception' element is empty, it will default to the exception type(s) specified in the method's parameter list. There should be at most one exception type specified in the method parameter list.
- Return types
We can use @ResponseBody to return the error response straight from the method, return a view name, or — as of Spring Framework 6 — return a ProblemDetail or ErrorResponse object to produce a standardized RFC 9457 "problem details" error response body.
- Using @ResponseStatus
We can also optionally use @ResponseStatus along with @ExceptionHandler to specify the response status code.
- Scope
An @ExceptionHandler method defined directly inside a @Controller class only handles exceptions thrown by that same controller. To share exception-handling logic across multiple controllers, define the @ExceptionHandler methods instead in a class annotated with @ControllerAdvice (or @RestControllerAdvice for REST APIs) — those methods apply globally, or to a targeted subset of controllers if the advice is scoped.
- Ambiguity
Mapping exactly the same exception type with multiple @ExceptionHandler methods within the same scope will cause this exception
java.lang.IllegalStateException: Ambiguous @ExceptionHandler method mapped for ........................
- Background processing
In the background, ExceptionHandlerExceptionResolver (an implementation of HandlerExceptionResolver) is used for exception resolving and invoking the @ExceptionHandler methods for us. By default, its instance is configured with DispatcherServlet, so we don't have to do any related configuration to use it.
Example
Example Controller
In the following controller, three handler methods throw different exceptions, and three methods are defined with @ExceptionHandler. Before running the code, try to mentally match each thrown exception type to the corresponding @ExceptionHandler's value to work out which method will be invoked in each scenario.
package com.logicbig.example;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.ModelAndView;
import jakarta.servlet.http.HttpServletRequest;
import java.time.Year;
@Controller
public class ExampleController {
@RequestMapping("/data/{year}")
@ResponseBody
public String handleRequest(@PathVariable("year") int year) throws Exception {
if (Year.of(year).isBefore(Year.of(1990))) {
throw new Exception("Year is before 1990: " + year);
}
return "data response " + year;
}
@RequestMapping("/test/{id}")
@ResponseBody
public String handleRequest2(@PathVariable("id") String id) {
int i = Integer.parseInt(id);
return "test response " + i;
}
@RequestMapping("/admin")
@ResponseBody
public String handleRequest3(HttpServletRequest request)
throws UserNotLoggedInException {
Object user = request.getSession()
.getAttribute("user");
if (user == null) {
throw new UserNotLoggedInException("user: " + user);
}
return "test response " + user;
}
@ExceptionHandler(NumberFormatException.class)
public ModelAndView exceptionHandler(NumberFormatException re) {
ModelAndView mav = new ModelAndView("errorPage");
mav.addObject("exception", re);
return mav;
}
@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(Exception.class)
@ResponseBody
public String exceptionHandler2(Exception re) {
return "Exception: " + re.getMessage();
}
@ResponseStatus(HttpStatus.FORBIDDEN)
@ExceptionHandler(UserNotLoggedInException.class)
public ModelAndView exceptionHandler3(UserNotLoggedInException e) {
ModelAndView mav = new ModelAndView("errorPage");
mav.addObject("exception", e);
return mav;
}
}
package com.logicbig.example;
public class UserNotLoggedInException extends Exception {
public UserNotLoggedInException (String message) {
super(message);
}
}
src/main/webapp/WEB-INF/views/errorPage.jsp<%@ page language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<html>
<body>
<h3>This is custom exception page</h3>
<p>Exception Type: <b>${exception['class'].simpleName}</b></p>
<p>Exception Message: <b>${exception.message}</b></p>
</body>
</html>
Running the example
To try examples, run embedded Jetty (configured in pom.xml of example project below):
mvn jetty:run Output
We are going to show related code snippets to figure out the result easily.
/data/{year}
@Controller
public class ExampleController {
@RequestMapping("/data/{year}")
@ResponseBody
public String handleRequest(@PathVariable("year") int year) throws Exception {
if (Year.of(year).isBefore(Year.of(1990))) {
throw new Exception("Year is before 1990: " + year);
}
return "data response " + year;
}
.............
@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(Exception.class)
@ResponseBody
public String exceptionHandler2(Exception re) {
return "Exception: " + re.getMessage();
}
.............
}
$ curl -si "http://localhost:8080/exception-handler-annotation/data/2007" | findstr /V /R "^Date: ^Content- ^Server:"
HTTP/1.1 200 OK
data response 2007
$ curl -si "http://localhost:8080/exception-handler-annotation/data/1985" | findstr /V /R "^Date: ^Content- ^Server:"
HTTP/1.1 400 Bad Request
Exception: Year is before 1990: 1985
/test/{id}
@Controller
public class ExampleController {
.............
@RequestMapping("/test/{id}")
@ResponseBody
public String handleRequest2(@PathVariable("id") String id) {
int i = Integer.parseInt(id);
return "test response " + i;
}
.............
@ExceptionHandler(NumberFormatException.class)
public ModelAndView exceptionHandler(NumberFormatException re) {
ModelAndView mav = new ModelAndView("errorPage");
mav.addObject("exception", re);
return mav;
}
.............
}
$ curl -si "http://localhost:8080/exception-handler-annotation/test/2" | findstr /V /R "^Date: ^Content- ^Server:"
HTTP/1.1 200 OK
test response 2
$ curl -si "http://localhost:8080/exception-handler-annotation/test/abc" | findstr /V /R "^Date: ^Content- ^Server: ^Set-Cookie: ^Expires:"
HTTP/1.1 200 OK
<html>
<body>
<h3>This is custom exception page</h3>
<p>Exception Type: <b>NumberFormatException</b></p>
<p>Exception Message: <b>For input string: "abc"</b></p>
</body>
</html>
/admin
@Controller
public class ExampleController {
.............
@RequestMapping("/admin")
@ResponseBody
public String handleRequest3(HttpServletRequest request)
throws UserNotLoggedInException {
Object user = request.getSession()
.getAttribute("user");
if (user == null) {
throw new UserNotLoggedInException("user: " + user);
}
return "test response " + user;
}
.............
@ResponseStatus(HttpStatus.FORBIDDEN)
@ExceptionHandler(UserNotLoggedInException.class)
public ModelAndView exceptionHandler3(UserNotLoggedInException e) {
ModelAndView mav = new ModelAndView("errorPage");
mav.addObject("exception", e);
return mav;
}
}
$ curl -si "http://localhost:8080/exception-handler-annotation/admin" | findstr /V /R "^Date: ^Content- ^Server: ^Set-Cookie: ^Expires:"
HTTP/1.1 403 Forbidden
<html>
<body>
<h3>This is custom exception page</h3>
<p>Exception Type: <b>UserNotLoggedInException</b></p>
<p>Exception Message: <b>user: null</b></p>
</body>
</html>
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 3.2.9.RELEASE - 7.0.6 Version compatibilities of spring-webmvc with this example: Versions in green have been tested.
- jakarta.servlet-api 6.1.0 (Jakarta Servlet API documentation)
- JDK 25
- Maven 3.9.11
|
