Global Exception Handling with @ControllerAdvice

1. The Problem: Scattered and Inconsistent Error Handling

Without a global strategy, you're forced to handle exceptions directly in your controllers.

This approach has several major drawbacks:

• Code Duplication: The same error-handling logic is repeated across many controller methods.
• Mixed Concerns: Your controller methods become bloated with error-handling code, obscuring the primary business logic.
• Inconsistency: Different methods might return differently structured error messages for the same type of error.

The solution is to centralize this logic.

2. The Solution: @ControllerAdvice and @ExceptionHandler

Spring provides two powerful annotations that work together to create a global exception handling component:

• @ControllerAdvice: This annotation marks a class as a "global controller advisor." It's a specialized @Component that allows you to share logic across all of your controllers. It acts as an interceptor, catching exceptions that are thrown from your controller methods.
• @ExceptionHandler: You place this annotation on a method within a @ControllerAdvice class. It specifies which exception (or exceptions) the method is responsible for handling.

When an exception is thrown from a controller, Spring looks for an @ExceptionHandler method within any @ControllerAdvice bean that can handle that specific exception type.

This diagram illustrates the flow:

3. Implementing a Global Exception Handler

Let's build a global exception handler step-by-step. We will start by handling a very common scenario: a resource not being found.

Step 3.1: The Default Error Experience

First, let's see what happens by default when an unhandled exception occurs.

As you can see, the default response leaks implementation details (Internal Server Error) and lacks a clear, structured message for the API consumer.

Step 3.2: Creating the Handler and a Custom Error Response

To fix this, we'll create a new class. A common best practice is to have this class extend ResponseEntityExceptionHandler. This Spring class provides built-in handling for standard Spring MVC exceptions, which you can then override and customize if needed.

// In a new package, e.g., com.example.yourapp.exception
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
    // We will add our handler methods here
}

Next, we need to define a standard structure for our error responses. We'll create a plain Java object (a DTO) for this purpose.

Your ErrorResponse class might look like this:

import java.time.LocalDateTime;

public class ErrorResponse {
    private int statusCode;
    private LocalDateTime timestamp;
    private String message;
    private String description;

    // Constructors, Getters...
}

Step 3.3: Handling Specific Exceptions

Now we can add a method to our GlobalExceptionHandler to handle the NoSuchElementException you saw earlier.

Here's what that handler method would look like:

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.context.request.WebRequest;
import java.util.NoSuchElementException;

// Inside your GlobalExceptionHandler class...

@ExceptionHandler(NoSuchElementException.class)
public ResponseEntity<Object> handleNoSuchElementException(NoSuchElementException ex, WebRequest request) {
    ErrorResponse message = new ErrorResponse(
        HttpStatus.NOT_FOUND.value(),
        LocalDateTime.now(),
        ex.getMessage(),
        request.getDescription(false) // This gets the URI path
    );
    
    return new ResponseEntity<>(message, HttpStatus.NOT_FOUND);
}

With this in place, any time NoSuchElementException is thrown from any controller, this handler will catch it and return a clean, informative 404 Not Found response.

4. A Cleaner Design: Custom Exceptions

Catching NoSuchElementException is good, but it has a flaw: it tightly couples our web layer (the exception handler) to an implementation detail of the persistence layer. A better design is to use your own custom exceptions to represent business-rule violations.

This three-step pattern is extremely powerful:

1. Define a Custom Exception:

   public class ResourceNotFoundException extends RuntimeException {
       public ResourceNotFoundException(String message) {
           super(message);
       }
   }
   

2. Throw it from your Service/Controller:

   // In your service or controller
   User user = userRepository.findById(id)
       .orElseThrow(() -> new ResourceNotFoundException("User not found with id: " + id));
   

3. Handle it in the GlobalExceptionHandler:

   @ExceptionHandler(ResourceNotFoundException.class)
   public ResponseEntity<Object> handleResourceNotFoundException(ResourceNotFoundException ex, WebRequest request) {
       // ... create and return your ErrorResponse with HttpStatus.NOT_FOUND
   }
   

This decouples your API's error contract from underlying implementation details.

5. The Catch-All Handler and @RestControllerAdvice

What happens if an unexpected error occurs—one you don't have a specific handler for? To prevent ugly stack traces from being sent to the client, you should always include a "catch-all" handler for the base Exception.class.

// Inside your GlobalExceptionHandler class...

@ExceptionHandler(Exception.class)
public ResponseEntity<Object> handleGlobalException(Exception ex, WebRequest request) {
    ErrorResponse message = new ErrorResponse(
        HttpStatus.INTERNAL_SERVER_ERROR.value(),
        LocalDateTime.now(),
        "An unexpected error occurred",
        ex.getLocalizedMessage() // Or a more generic message for production
    );
    
    return new ResponseEntity<>(message, HttpStatus.INTERNAL_SERVER_ERROR);
}

Finally, since we are building a REST API, we can use a more convenient annotation: @RestControllerAdvice.

When you use @RestControllerAdvice, Spring automatically handles serializing your return object to JSON and setting the response body. You can still return ResponseEntity if you need to control headers, but for simple cases, you can return your DTO directly.

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import java.time.LocalDateTime;

@RestControllerAdvice
public class GlobalExceptionHandler {

    // ... other handlers ...

    @ExceptionHandler(DuplicateUsernameException.class)
    @ResponseStatus(HttpStatus.CONFLICT) // Sets the HTTP status code
    public ErrorResponse handleDuplicateUsernameException(DuplicateUsernameException ex, WebRequest request) {
        return new ErrorResponse(
            HttpStatus.CONFLICT.value(),
            LocalDateTime.now(),
            ex.getMessage(),
            request.getDescription(false)
        );
    }
}

Conclusion

Excellent work! You have now learned how to build a robust, centralized exception handling mechanism for your entire API. This is a critical skill for creating professional, maintainable, and user-friendly backend services.

Key Takeaways:

• Use @RestControllerAdvice to create a global exception handling component for REST APIs.
• Use @ExceptionHandler on methods to handle specific exception types.
• Create custom error DTOs (e.g., ErrorResponse) to ensure a consistent JSON structure for all errors.
• Prefer defining and throwing your own custom exceptions (e.g., ResourceNotFoundException) to represent business errors, keeping your API decoupled from implementation details.
• Always include a catch-all handler for Exception.class to gracefully manage unexpected errors and return an HTTP 500 Internal Server Error.
• The most appropriate HTTP status codes for common errors are 404 NOT FOUND (resource missing), 400 BAD REQUEST (client error, like invalid data), and 409 CONFLICT (duplicate resource).

What's Next?

With robust validation and consistent error handling in place, your API's foundation is becoming very solid. In the next module, "API Design and Data Transfer Objects," we'll shift our focus to the "contract" of the API itself. We will start by learning how to apply RESTful URI naming conventions for resources, ensuring that your API endpoints are intuitive, predictable, and easy for other developers to use.