@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.