@ExceptionHandler in controllers in Spring Boot - Step-by-Step Execution

Concept Flow - @ExceptionHandler in controllers

Controller method called

↓

Exception thrown?

No→Return normal response

Yes↓

@ExceptionHandler method matches exception type?

No→Unhandled exception

Yes↓

@ExceptionHandler method runs

↓

Return error response to client

When a controller method throws an exception, Spring looks for a matching @ExceptionHandler method to handle it and send a custom response.

Execution Sample

Spring Boot

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 MyController {
  @GetMapping("/data")
  public String getData() {
    throw new IllegalArgumentException("Bad input");
  }

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

This controller throws an exception in getData(), which is caught by the @ExceptionHandler method to return a 400 error with a message.

Execution Table

Step	Action	Exception Thrown?	ExceptionHandler Found?	Response Sent
1	Client calls GET /data	No	N/A	N/A
2	getData() executes	Yes: IllegalArgumentException	N/A	N/A
3	Spring searches for @ExceptionHandler for IllegalArgumentException	N/A	Yes: handleBadInput()	N/A
4	handleBadInput() runs with exception	N/A	N/A	ResponseEntity with 400 and message
5	Response sent to client	N/A	N/A	400 Bad Request with 'Error: Bad input'

💡 Exception handled by @ExceptionHandler method, response sent with error message.

Variable Tracker

Variable	Start	After Step 2	After Step 4	Final
exception	null	IllegalArgumentException("Bad input")	Passed to handleBadInput()	Handled and response created
response	null	null	ResponseEntity.badRequest().body("Error: Bad input")	Sent to client

Key Moments - 3 Insights

Why does the normal controller method not return a response when an exception is thrown?

Because the exception interrupts normal flow at Step 2 in the execution_table, so no normal response is returned. Instead, Spring looks for an @ExceptionHandler to handle it.

What happens if there is no matching @ExceptionHandler for the thrown exception?

Spring will not find a handler at Step 3, so the exception remains unhandled and usually results in a default error response or server error.

How does Spring know which @ExceptionHandler method to run?

It matches the exception type thrown (IllegalArgumentException) with the exception class declared in the @ExceptionHandler annotation, as shown in Step 3.

Visual Quiz - 3 Questions

Look at the execution_table, what exception is thrown at Step 2?

A NullPointerException

B IOException

C IllegalArgumentException with message 'Bad input'

D No exception thrown

💡 Hint

Check the 'Exception Thrown?' column at Step 2 in the execution_table.

At which step does Spring find the matching @ExceptionHandler method?

A Step 1

B Step 3

C Step 4

D Step 5

💡 Hint

Look at the 'ExceptionHandler Found?' column in the execution_table.

If the exception thrown was NullPointerException instead, what would change in the execution_table?

A Step 3 would show no matching @ExceptionHandler found

B Step 4 would run handleBadInput() anyway

C Step 2 would not throw an exception

D Response would be 200 OK

💡 Hint

Refer to how Spring matches exception types to @ExceptionHandler methods in Step 3.

Concept Snapshot

@ExceptionHandler in controllers:
- Use @ExceptionHandler(ExceptionType.class) on a method
- Handles exceptions thrown by controller methods
- Spring calls matching handler when exception occurs
- Handler returns custom response (e.g., error message)
- Prevents server error by managing exceptions gracefully

Full Transcript

When a client calls a controller method, the method runs normally unless it throws an exception. If an exception occurs, Spring looks for a method annotated with @ExceptionHandler that matches the exception type. If found, Spring runs that method to handle the exception and send a custom error response to the client. This prevents the server from returning a generic error and allows friendly error messages. If no handler matches, the exception is unhandled and results in a default error response. The example shows a controller throwing IllegalArgumentException, which is caught by a matching @ExceptionHandler method returning a 400 Bad Request with a message.

Practice

1. What is the main purpose of using @ExceptionHandler in a Spring Boot controller?

easy

A. To catch and handle exceptions thrown in controller methods

B. To define the URL path for a controller method

C. To inject dependencies into the controller

D. To configure database connections

Solution

1. Step 1: Understand the role of @ExceptionHandler

   @ExceptionHandler is used to catch exceptions that occur in controller methods to prevent the app from crashing.

2. Step 2: Identify what @ExceptionHandler does in controllers

   It allows sending user-friendly error messages and proper HTTP status codes when exceptions happen.

3. Final Answer:

   To catch and handle exceptions thrown in controller methods -> Option A

4. Quick Check:

   @ExceptionHandler catches exceptions [OK]

Hint: Remember: @ExceptionHandler handles errors in controllers [OK]

Common Mistakes:

• Confusing @ExceptionHandler with URL mapping annotations
• Thinking it injects dependencies
• Assuming it configures database settings

2. Which of the following is the correct way to declare an exception handler method in a Spring Boot controller?

easy

A. @RequestMapping(Exception.class) public String handleError() { return "error"; }

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

C. @Autowired(Exception.class) public String handleError() { return "error"; }

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

Solution

1. Step 1: Identify the correct annotation for exception handling

   @ExceptionHandler is the annotation used to mark methods that handle exceptions.

2. Step 2: Check the method signature

   The method should be annotated with @ExceptionHandler(Exception.class) and return a response, here a String view name.

3. Final Answer:

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

4. Quick Check:

   @ExceptionHandler syntax [OK]

Hint: Use @ExceptionHandler with exception class to handle errors [OK]

Common Mistakes:

• Using @RequestMapping or @GetMapping instead of @ExceptionHandler
• Misusing @Autowired annotation
• Missing the exception class in @ExceptionHandler

3. Given the following controller code snippet, what will be the HTTP status code returned when a NullPointerException occurs?

@RestController
public class MyController {
  @GetMapping("/test")
  public String test() {
    throw new NullPointerException("Null error");
  }

  @ExceptionHandler(NullPointerException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  public String handleNullPointer() {
    return "Null pointer error handled";
  }
}

medium

A. 200 OK

B. 400 Bad Request

C. 500 Internal Server Error

D. 404 Not Found

Solution

1. Step 1: Identify the exception and handler

   The controller throws NullPointerException, which is caught by the method annotated with @ExceptionHandler(NullPointerException.class).

2. Step 2: Check the response status annotation

   The handler method has @ResponseStatus(HttpStatus.BAD_REQUEST), so it sets the HTTP status to 400.

3. Final Answer:

   400 Bad Request -> Option B

4. Quick Check:

   @ResponseStatus sets HTTP code = 400 [OK]

Hint: Look for @ResponseStatus on @ExceptionHandler method [OK]

Common Mistakes:

• Assuming default 500 error without @ResponseStatus
• Confusing exception type with HTTP status
• Ignoring the @ExceptionHandler method

4. Consider this controller code snippet:

@RestController
public class DemoController {
  @GetMapping("/demo")
  public String demo() {
    throw new IllegalArgumentException("Invalid argument");
  }

  @ExceptionHandler(NullPointerException.class)
  public String handleNull() {
    return "Null error";
  }
}

What will happen when the /demo endpoint is called?

medium

A. The exception will be handled by handleNull method

B. The response will be "Null error" with HTTP 200

C. The exception will not be handled and a 500 error is returned

D. The server will return HTTP 404 Not Found

Solution

1. Step 1: Identify the thrown exception

   The method throws IllegalArgumentException, but the handler only catches NullPointerException.

2. Step 2: Check if exception is handled

   Since no handler matches IllegalArgumentException, Spring Boot returns a default 500 Internal Server Error.

3. Final Answer:

   The exception will not be handled and a 500 error is returned -> Option C

4. Quick Check:

   Handler mismatch causes 500 error [OK]

Hint: Handler must match exception type exactly [OK]

Common Mistakes:

• Assuming handler catches all exceptions
• Thinking handler method runs for different exception types
• Expecting 404 instead of 500 error

5. You want to create a global exception handler in Spring Boot that catches RuntimeException for all controllers and returns a JSON error message with HTTP status 500. Which approach correctly achieves this?

hard

A. Create a class annotated with @ControllerAdvice and define a method with @ExceptionHandler(RuntimeException.class) returning a JSON response and @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR).

B. Add @ExceptionHandler(RuntimeException.class) method inside each controller class returning a view name.

C. Use @RestController on a class with @ExceptionHandler(Exception.class) returning a String message.

D. Configure exception handling in application.properties file.

Solution

1. Step 1: Understand global exception handling

   @ControllerAdvice allows defining exception handlers that apply to all controllers globally.

2. Step 2: Define handler method for RuntimeException

   Use @ExceptionHandler(RuntimeException.class) with @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR) to set status 500 and return JSON response.

3. Final Answer:

   Create a class annotated with @ControllerAdvice and define a method with @ExceptionHandler(RuntimeException.class) returning a JSON response and @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR). -> Option A

4. Quick Check:

   Global handler uses @ControllerAdvice + @ExceptionHandler [OK]

Hint: Use @ControllerAdvice for global exception handling [OK]

Common Mistakes:

• Putting handlers only inside controllers for global effect
• Using application.properties for exception handling
• Not setting proper HTTP status in handler