How to Use @ExceptionHandler in Spring for Error Handling

Use @ExceptionHandler in a Spring controller or @ControllerAdvice class to define methods that handle specific exceptions. Annotate a method with @ExceptionHandler(ExceptionType.class) to catch and respond to that exception type during request processing.

Syntax

The @ExceptionHandler annotation marks a method to handle exceptions of specified types thrown in controller methods. It can be placed inside a controller class or a global @ControllerAdvice class.

• @ExceptionHandler(ExceptionType.class): Specifies which exception(s) the method handles.
• Method parameters can include the exception object and optionally WebRequest or HttpServletRequest.
• The method returns a response body, view name, or ResponseEntity to send an error response.

java

public class MyController {

    @ExceptionHandler(IllegalArgumentException.class)
    public String handleIllegalArgument(IllegalArgumentException ex) {
        return "error-illegal-argument"; // view name or error message
    }

}

Example

This example shows a controller with a method that throws an exception and an @ExceptionHandler method that catches it and returns a friendly error message.

java

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/test")
    public String test() {
        throw new IllegalArgumentException("Invalid argument passed");
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<String> handleIllegalArgument(IllegalArgumentException ex) {
        return ResponseEntity.badRequest().body("Error: " + ex.getMessage());
    }
}

Output

HTTP 400 Bad Request
Body: Error: Invalid argument passed

Common Pitfalls

• Not specifying the exception class in @ExceptionHandler causes it to handle all exceptions, which may hide errors.
• Placing @ExceptionHandler methods in unrelated classes without @ControllerAdvice prevents them from being called.
• Returning incorrect response types can cause Spring to fail rendering the error response.

java

/* Wrong: Missing exception class, catches all exceptions unintentionally */
@ExceptionHandler
public String handleAllExceptions(Exception ex) {
    return "generic-error";
}

/* Right: Specify exception class explicitly */
@ExceptionHandler(NullPointerException.class)
public String handleNullPointer(NullPointerException ex) {
    return "null-pointer-error";
}

Quick Reference

Feature	Description
@ExceptionHandler(ExceptionType.class)	Handles specified exception type(s) in controller or @ControllerAdvice
Method Parameters	Can include exception object, WebRequest, HttpServletRequest
Return Types	String (view), ResponseEntity, or any response body
Placement	Inside controller class or global @ControllerAdvice class
Multiple Exceptions	Use array: @ExceptionHandler({Ex1.class, Ex2.class})

Key Takeaways

Use @ExceptionHandler on methods to catch and handle specific exceptions in Spring controllers.

Place @ExceptionHandler methods inside controllers or @ControllerAdvice classes for global handling.

Specify the exception class explicitly to avoid catching unintended exceptions.

Return appropriate response types like ResponseEntity or view names for error responses.

Use @ExceptionHandler with multiple exceptions by listing them in an array.