@ControllerAdvice (Global Exception Handling)

In Spring Boot, @ControllerAdvice is a global exception handling mechanism that intercepts exceptions thrown by any controller. It allows you to:

• Centralize error handling
• Avoid repeated code in controllers
• Return consistent, structured JSON responses for REST APIs

For REST APIs, use @RestControllerAdvice, which automatically returns JSON responses instead of HTML.

What is @ControllerAdvice?

• A Spring annotation that marks a class as a global exception handler.
• Works with @ExceptionHandler methods inside the class.
• Handles exceptions thrown by all controllers.
• Can manage validation errors like MethodArgumentNotValidException.
• Ensures consistent error responses for clients.

In short:

@ControllerAdvice = centralized exception management for your Spring Boot app.

Why Use @ControllerAdvice?

• Centralized Handling: Avoids repeating @ExceptionHandler in every controller.
• Cleaner Controllers: Focus on business logic instead of error handling.
• Consistent API Responses: All errors follow the same JSON format.
• Easier Maintenance: Update exception handling in one place.
• Professional APIs: Return structured JSON instead of plain text.

Basic Example

This example shows handling a specific exception, a generic exception, and validation errors globally.

@RestControllerAdvice
publicclassGlobalExceptionHandler {

// Handle specific exception
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse>handleUserNotFound(UserNotFoundException ex) {
ErrorResponseerror=newErrorResponse(
                ex.getMessage(),
                HttpStatus.NOT_FOUND.value(),
                System.currentTimeMillis()
        );
returnnewResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

// Handle all other exceptions
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse>handleAllExceptions(Exception ex) {
ErrorResponseerror=newErrorResponse(
"Something went wrong",
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                System.currentTimeMillis()
        );
returnnewResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }

// Handle validation errors globally
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, Object>>handleValidationErrors(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(error -> error.getField() +": " + error.getDefaultMessage())
                .toList();

        Map<String, Object> response =newHashMap<>();
        response.put("timestamp", System.currentTimeMillis());
        response.put("status", HttpStatus.BAD_REQUEST.value());
        response.put("errors", errors);

return ResponseEntity.badRequest().body(response);
    }
}

Error Response DTO Example

The ErrorResponse DTO standardizes the JSON response format for all exceptions. The errors field can hold a list of validation errors, making responses clear and structured.

publicclassErrorResponse {
private String message;
privateint status;
private Object errors;// Can hold validation error list
privatelong timestamp;

publicErrorResponse(String message, int status, Object errors) {
this.message = message;
this.status = status;
this.errors = errors;
this.timestamp = System.currentTimeMillis();
    }

// Getters and setters
}

Example JSON Responses

UserNotFoundException: Shows a specific exception with a 404 HTTP status**.**

{
"message":"User not found",
"status":404,
"timestamp":1672567890123
}

Generic Exception: Represents any unhandled exceptions globally with a 500 HTTP status.

{
"message":"Something went wrong",
"status":500,
"timestamp":1672567890123
}

Validation Error: Shows detailed validation errors returned as a list for client feedback.

{
"timestamp":1672567890123,
"status":400,
"errors":[
"name: Name is required",
"email: Email should be valid",
"age: Age must be at least 18"
]
}

Flow of @ControllerAdvice

This flow shows how exceptions propagate from any controller to the global handler, and a structured JSON response is returned to the client.

Exception Thrown in Any Controller
            |
            v
  Global @ControllerAdvice Handler
            |
            v
   Appropriate @ExceptionHandler Executes
            |
            v
  Returns Structured JSON Response

Scope of @ControllerAdvice

@ControllerAdvice is designed for centralized, reusable exception handling, making it ideal for large REST APIs and microservices.

Advantages of @ControllerAdvice

Difference Between @ExceptionHandler and @ControllerAdvice

Conclusion:

@ControllerAdvice is the preferred approach for global exception handling in Spring Boot. It ensures:

• Centralized and reusable error handling
• Structured, user-friendly JSON responses
• Clean, professional, and maintainable REST APIs

Use @RestControllerAdvice for REST APIs to automatically return JSON responses without additional configuration.