@ControllerAdvice for global handling in Spring Boot - Deep Dive

Overview - @ControllerAdvice for global handling

What is it?

@ControllerAdvice is a special feature in Spring Boot that lets you handle errors and exceptions in one place for all your web controllers. Instead of writing error handling code in every controller, you write it once here. It helps keep your code clean and consistent. It can also customize responses when something goes wrong.

Why it matters

Without @ControllerAdvice, you would have to repeat error handling in every controller, making your code messy and harder to maintain. It also risks inconsistent error messages for users. Using @ControllerAdvice means you can fix bugs or change error responses in one place, improving reliability and user experience.

Where it fits

Before learning @ControllerAdvice, you should understand basic Spring Boot controllers and exception handling. After mastering it, you can explore advanced error handling techniques like ResponseEntityExceptionHandler and customizing error responses with JSON or views.

Mental Model

Core Idea

@ControllerAdvice acts like a global safety net that catches and handles errors from all controllers in one central place.

Think of it like...

Imagine a building with many rooms (controllers). Instead of having a fire extinguisher in every room, you install a sprinkler system (@ControllerAdvice) that covers the whole building and activates when needed.

┌─────────────────────────────┐
│        @ControllerAdvice     │
│  (Global Error Handler)      │
└─────────────┬───────────────┘
              │
  ┌───────────┴───────────┐
  │ Controllers (Room 1)   │
  │ Controllers (Room 2)   │
  │ Controllers (Room 3)   │
  └───────────────────────┘

Errors from any controller flow up to @ControllerAdvice for handling.

Build-Up - 7 Steps

1

Foundation

Understanding Spring Controllers

Concept: Learn what a Spring Boot controller is and how it handles web requests.

A Spring Boot controller is a class annotated with @RestController or @Controller. It listens for web requests on specific URLs and returns responses. For example, a method annotated with @GetMapping("/hello") returns a greeting when someone visits /hello.

Result

You can create simple web endpoints that respond to user requests.

Knowing how controllers work is essential because @ControllerAdvice works by intercepting errors from these controllers.

2

Foundation

Basic Exception Handling in Controllers

Concept: Learn how to handle errors inside a single controller using @ExceptionHandler.

Inside a controller, you can add methods annotated with @ExceptionHandler(ExceptionType.class) to catch specific exceptions thrown by that controller's methods. This lets you return custom error messages or status codes.

Result

Errors in that controller are caught and handled gracefully, improving user experience.

This shows the problem @ControllerAdvice solves: handling exceptions controller-by-controller is repetitive and scattered.

3

Intermediate

Introducing @ControllerAdvice for Global Handling

🤔Before reading on: do you think @ControllerAdvice handles errors only for one controller or for all controllers? Commit to your answer.

Concept: @ControllerAdvice lets you write exception handling code once and apply it to all controllers globally.

Annotate a class with @ControllerAdvice and add @ExceptionHandler methods inside it. These methods catch exceptions thrown by any controller in your app. For example, if any controller throws NullPointerException, the global handler can catch it and return a friendly message.

Result

All controllers share the same error handling logic, reducing code duplication.

Understanding that @ControllerAdvice centralizes error handling helps you write cleaner, more maintainable code.

4

Intermediate

Customizing Responses with @ExceptionHandler

🤔Before reading on: do you think @ExceptionHandler methods can return different response types like JSON or views? Commit to your answer.

Concept: @ExceptionHandler methods inside @ControllerAdvice can return various response types to customize error output.

You can return ResponseEntity objects with custom HTTP status codes and JSON bodies, or return view names for error pages. For example, returning ResponseEntity.status(404).body("Not Found") sends a 404 status with a message.

Result

Users get meaningful error messages and proper HTTP status codes.

Knowing how to customize responses lets you improve API usability and user experience.

5

Intermediate

Using @ResponseStatus for Simple Error Codes

Concept: Learn how to use @ResponseStatus on exception classes or handler methods to set HTTP status codes easily.

Annotate an exception class with @ResponseStatus(HttpStatus.NOT_FOUND) to automatically send a 404 status when that exception is thrown. Or annotate a handler method with @ResponseStatus to set status without building ResponseEntity.

Result

Simpler code for common HTTP error responses.

This shortcut reduces boilerplate and keeps error handling concise.

6

Advanced

Extending ResponseEntityExceptionHandler for Common Errors

🤔Before reading on: do you think extending ResponseEntityExceptionHandler is necessary or optional for global error handling? Commit to your answer.

Concept: Spring provides ResponseEntityExceptionHandler, a base class with methods to handle common Spring MVC exceptions. You can extend it to customize or add handlers.

Create a class annotated with @ControllerAdvice that extends ResponseEntityExceptionHandler. Override methods like handleMethodArgumentNotValid to customize validation error responses globally.

Result

You get fine control over many common error scenarios with less code.

Knowing this base class lets you leverage Spring's built-in error handling and customize it efficiently.

7

Expert

Order and Scope of Multiple @ControllerAdvice Classes

🤔Before reading on: if multiple @ControllerAdvice classes exist, do you think all handle errors equally or is there an order and scope? Commit to your answer.

Concept: You can have multiple @ControllerAdvice classes with different scopes and priorities controlling which handles errors first.

Use @Order to set priority among multiple @ControllerAdvice classes. Use annotations like @RestControllerAdvice to limit scope to REST controllers. This helps organize error handling in large apps.

Result

You can build layered, modular global error handling tailored to different parts of your app.

Understanding order and scope prevents conflicts and unexpected error handling behavior in complex projects.

Under the Hood

@ControllerAdvice is a Spring component scanned at startup. It registers exception handler methods globally in the DispatcherServlet's exception resolver chain. When a controller method throws an exception, Spring looks for matching @ExceptionHandler methods first in the controller, then in @ControllerAdvice classes by order. The matching handler method is invoked to produce the response.

Why designed this way?

Spring designed @ControllerAdvice to separate cross-cutting concerns like error handling from business logic. This keeps controllers focused on request handling. The global approach avoids code duplication and allows consistent error responses. Alternatives like handling exceptions only in controllers were too repetitive and error-prone.

┌───────────────────────────────┐
│        DispatcherServlet       │
│  (Handles incoming requests)  │
└─────────────┬─────────────────┘
              │
      ┌───────┴────────┐
      │ Controller      │
      │ (Handles URL)   │
      └───────┬────────┘
              │ Throws Exception
              ▼
┌───────────────────────────────┐
│ @ControllerAdvice Classes      │
│ (Global Exception Handlers)    │
└─────────────┬─────────────────┘
              │
      ┌───────┴────────┐
      │ ExceptionHandler│
      │ Method Called   │
      └────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does @ControllerAdvice handle exceptions only for REST controllers or for all controllers? Commit to your answer.

Common Belief: Many think @ControllerAdvice only works with REST controllers (@RestController).

Reality: @ControllerAdvice works with all controllers, including @Controller and @RestController. You can limit scope with annotations but by default it is global.

Why it matters: Assuming it only works for REST controllers may cause missing error handling in MVC controllers, leading to inconsistent behavior.

Quick: Do you think @ExceptionHandler methods in @ControllerAdvice override those in controllers or run alongside? Commit to your answer.

Common Belief: Some believe global handlers override controller-level handlers always.

Reality: Controller-level @ExceptionHandler methods have higher priority. Global handlers are fallback if no controller handler matches.

Why it matters: Misunderstanding this can cause confusion when controller handlers seem ignored or global handlers unexpectedly catch exceptions.

Quick: Can @ControllerAdvice handle exceptions thrown outside controller methods, like in filters or services? Commit to your answer.

Common Belief: Many think @ControllerAdvice catches all exceptions in the app.

Reality: @ControllerAdvice only handles exceptions thrown during controller method execution. Exceptions in filters, services, or async threads are not caught here.

Why it matters: Expecting global handling everywhere can lead to unhandled exceptions and crashes if other layers are not protected.

Quick: Does using @ControllerAdvice guarantee thread safety of exception handlers? Commit to your answer.

Common Belief: Some assume exception handler methods are thread-safe by default.

Reality: @ControllerAdvice beans are singletons and shared across threads. Handler methods must be stateless or thread-safe.

Why it matters: Ignoring thread safety can cause bugs or data leaks in concurrent web requests.

Expert Zone

1

Exception handler methods can accept parameters like WebRequest, HttpServletRequest, or Exception to customize responses based on request details.

2

You can combine @ControllerAdvice with @RestControllerAdvice to automatically add @ResponseBody, simplifying REST API error handling.

3

Using @Order on multiple @ControllerAdvice classes controls which handler runs first, enabling layered error handling strategies.

When NOT to use

Avoid using @ControllerAdvice for handling exceptions outside the web layer, such as in background jobs or service layers. Use other mechanisms like AOP or try-catch blocks there. Also, for very simple apps, local controller exception handling might be sufficient.

Production Patterns

In real-world apps, teams create multiple @ControllerAdvice classes grouped by function (e.g., validation errors, authentication errors). They extend ResponseEntityExceptionHandler to customize common Spring MVC exceptions. They also log exceptions centrally and return consistent JSON error formats for APIs.

Connections

Aspect-Oriented Programming (AOP)

Both separate cross-cutting concerns like error handling from business logic.

Understanding @ControllerAdvice as a specialized AOP use case helps grasp how Spring modularizes concerns globally.

Middleware in Express.js (Node.js)

Both provide centralized error handling layers in web frameworks.

Knowing Express middleware error handling clarifies how @ControllerAdvice fits as a global error interceptor in Spring Boot.

Centralized Logging Systems

Global error handlers often integrate with centralized logging to track issues.

Seeing @ControllerAdvice as part of a larger error monitoring strategy helps appreciate its role beyond just returning responses.

Common Pitfalls

#1 Trying to handle exceptions in @ControllerAdvice but forgetting to annotate methods with @ExceptionHandler.

Wrong approach:

public class GlobalHandler {
public String handleNullPointer(Exception e) {
return "Error occurred";
}
}

Correct approach:

import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ControllerAdvice;
@ControllerAdvice
public class GlobalHandler {
@ExceptionHandler(NullPointerException.class)
public String handleNullPointer(Exception e) {
return "Error occurred";
}
}

Root cause:

Without @ExceptionHandler, Spring does not recognize the method as an exception handler.

#2 Returning plain String from @ExceptionHandler without @ResponseBody or ResponseEntity in REST APIs.

Wrong approach:

@ControllerAdvice
public class GlobalHandler {
@ExceptionHandler(Exception.class)
public String handleAll(Exception e) {
return "Error happened";
}
}

Correct approach:

@RestControllerAdvice
public class GlobalHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity handleAll(Exception e) {
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Error happened");
}
}

Root cause:

Returning String without @ResponseBody causes Spring to treat it as a view name, leading to errors in REST APIs.

#3 Assuming @ControllerAdvice catches exceptions thrown in asynchronous methods without special configuration.

Wrong approach:

@ControllerAdvice
public class GlobalHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity handleAll(Exception e) {
return ResponseEntity.status(500).body("Error");
}
}

// Async method throwing exception
@Async
public void asyncMethod() {
throw new RuntimeException("Fail");
}

Correct approach:

Handle async exceptions with AsyncUncaughtExceptionHandler or CompletableFuture exception handling, not @ControllerAdvice.

Root cause:

@ControllerAdvice only handles exceptions in the main web request thread.

Key Takeaways

@ControllerAdvice centralizes error handling for all Spring Boot controllers, reducing code duplication and improving consistency.

It works by defining global @ExceptionHandler methods that catch exceptions thrown during controller execution.

You can customize error responses with HTTP status codes, JSON bodies, or views to improve user experience.

Multiple @ControllerAdvice classes can coexist with order and scope control for complex applications.

Understanding its limitations, like not handling async exceptions, is key to using it effectively in production.

Practice

1. What is the main purpose of using @ControllerAdvice in a Spring Boot application?

easy

A. To handle exceptions globally for all controllers in one place

B. To define REST endpoints for the application

C. To configure database connections

D. To create scheduled tasks

Solution

1. Step 1: Understand the role of @ControllerAdvice

   @ControllerAdvice is a special annotation in Spring Boot that allows you to write code to handle exceptions or apply logic across all controllers globally.

2. Step 2: Identify its main use

   Its main use is to centralize exception handling so you don't have to repeat error handling code in every controller.

3. Final Answer:

   To handle exceptions globally for all controllers in one place -> Option A

4. Quick Check:

   @ControllerAdvice = global exception handling [OK]

Hint: Think global error handling for all controllers [OK]

Common Mistakes:

• Confusing @ControllerAdvice with @RestController
• Thinking it configures database or tasks
• Assuming it defines endpoints

2. Which of the following is the correct way to declare a global exception handler method inside a @ControllerAdvice class?

easy

A. @Service public String handleError() { return "error"; }

B. @ExceptionHandler(Exception.class) public String handleError() { return "error"; }

C. @GetMapping public String handleError() { return "error"; }

D. @RequestMapping("/error") public String handleError() { return "error"; }

Solution

1. Step 1: Identify the annotation for exception handling

   The correct annotation to handle exceptions globally is @ExceptionHandler with the exception class specified.

2. Step 2: Check method signature and annotation usage

   @ExceptionHandler(Exception.class) public String handleError() { return "error"; } uses @ExceptionHandler(Exception.class) which is correct inside a @ControllerAdvice class to catch all exceptions.

3. Final Answer:

   @ExceptionHandler(Exception.class) public String handleError() { return "error"; } -> Option B

4. Quick Check:

   @ExceptionHandler = global exception method [OK]

Hint: Use @ExceptionHandler with exception class inside @ControllerAdvice [OK]

Common Mistakes:

• Using @RequestMapping or @GetMapping instead of @ExceptionHandler
• Missing exception class in @ExceptionHandler
• Using @Service annotation incorrectly

3. Given the following code snippet, what will be the HTTP response status when a NullPointerException is thrown in any controller?

@ControllerAdvice
public class GlobalExceptionHandler {
  @ExceptionHandler(NullPointerException.class)
  public ResponseEntity<String> handleNullPointer() {
    return new ResponseEntity<>("Null pointer error", HttpStatus.BAD_REQUEST);
  }
}

medium

A. 400 Bad Request with message "Null pointer error"

B. 500 Internal Server Error with default message

C. 200 OK with message "Null pointer error"

D. 404 Not Found with message "Null pointer error"

Solution

1. Step 1: Analyze the @ExceptionHandler method

   The method handles NullPointerException and returns a ResponseEntity with message "Null pointer error" and status BAD_REQUEST.

2. Step 2: Understand HTTP status returned

   HttpStatus.BAD_REQUEST corresponds to 400 status code, so the response will have status 400 with the given message.

3. Final Answer:

   400 Bad Request with message "Null pointer error" -> Option A

4. Quick Check:

   @ExceptionHandler returns 400 status [OK]

Hint: Check ResponseEntity status in @ExceptionHandler method [OK]

Common Mistakes:

• Assuming default 500 error instead of specified status
• Confusing 400 with 200 OK
• Ignoring the returned ResponseEntity status

4. Consider this @ControllerAdvice class:

@ControllerAdvice
public class GlobalHandler {
  @ExceptionHandler(IllegalArgumentException.class)
  public String handleIllegalArgument() {
    return "illegal";
  }

  @ExceptionHandler(Exception.class)
  public String handleAll() {
    return "error";
  }
}

What is the problem if a NullPointerException occurs in a controller?

medium

A. NullPointerException is not handled and causes server error

B. handleIllegalArgument() method will handle NullPointerException incorrectly

C. handleAll() method will handle NullPointerException correctly

D. Compilation error due to multiple @ExceptionHandler methods

Solution

1. Step 1: Identify exception handlers and their scopes

   handleIllegalArgument() handles IllegalArgumentException only; handleAll() handles all Exceptions as a fallback.

2. Step 2: Determine which method handles NullPointerException

   Since NullPointerException is not IllegalArgumentException, handleAll() will catch it as it handles Exception class.

3. Final Answer:

   handleAll() method will handle NullPointerException correctly -> Option C

4. Quick Check:

   More specific handlers first, then general Exception handler [OK]

Hint: General @ExceptionHandler(Exception.class) catches all others [OK]

Common Mistakes:

• Thinking NullPointerException is unhandled
• Assuming multiple handlers cause compile error
• Confusing which handler matches which exception

5. You want to create a global error handler that returns JSON with error details for all exceptions except ResourceNotFoundException, which should return 404 status with a custom message. How should you implement this using @ControllerAdvice?

hard

A. Use a single @ExceptionHandler(Exception.class) method and check exception type inside to return different responses

B. Use @ControllerAdvice only for ResourceNotFoundException and ignore other exceptions

C. Handle ResourceNotFoundException in each controller separately, and use @ControllerAdvice only for other exceptions

D. Create two @ExceptionHandler methods: one for ResourceNotFoundException returning 404 JSON, another for Exception returning generic JSON with 500 status

Solution

1. Step 1: Understand requirement for specific and general handling

   You need one handler for ResourceNotFoundException with 404 and custom JSON, and another for all other exceptions with generic 500 JSON.

2. Step 2: Implement two separate @ExceptionHandler methods in @ControllerAdvice

   One method annotated with @ExceptionHandler(ResourceNotFoundException.class) returns 404 JSON; another with @ExceptionHandler(Exception.class) returns 500 JSON.

3. Final Answer:

   Create two @ExceptionHandler methods: one for ResourceNotFoundException returning 404 JSON, another for Exception returning generic JSON with 500 status -> Option D

4. Quick Check:

   Separate handlers for specific and general exceptions [OK]

Hint: Use multiple @ExceptionHandler methods for different exceptions [OK]

Common Mistakes:

• Using one method with manual type checks inside
• Handling specific exceptions in controllers, not globally
• Ignoring general exceptions in @ControllerAdvice