Spring Boot 4 Complete Guide · Lesson

Global Exception Handling with @ControllerAdvice

Centralize exception translation into clean HTTP responses using @ExceptionHandler and @ControllerAdvice.

Global Exception Handling with @ControllerAdvice is a free Spring Boot 4 Complete Guide lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Complete Guide learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Centralize Exception Handling?

When something goes wrong in a Spring Boot REST API, the client should receive a clean, predictable HTTP response, not a raw stack trace.

Without a strategy, you end up scattering try/catch blocks across every controller method, repeating the same JSON-building logic over and over.

Inconsistent status codes for the same error type
Duplicated error-response shaping
Leaked internal details (stack traces, SQL) to clients

Global exception handling solves this by translating exceptions into HTTP responses in one place.

The @ExceptionHandler Building Block

The core annotation is @ExceptionHandler. It marks a method that handles a specific exception type thrown during request processing.

Placed inside a controller, it only catches exceptions thrown by that controller's handler methods.

The method's parameter declares which exception it handles, and its return value becomes the HTTP response.

@RestController
public class ProductController {

    @GetMapping("/products/{id}")
    public Product getProduct(@PathVariable Long id) {
        throw new ProductNotFoundException(id);
    }

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

From Local to Global with @ControllerAdvice

A local @ExceptionHandler only covers one controller. To share handlers across the whole application, move them into a class annotated with @ControllerAdvice.

@ControllerAdvice is a specialization of @Component. Spring registers its @ExceptionHandler methods globally, so any controller that throws a matching exception is handled here.

For REST APIs, prefer @RestControllerAdvice, which combines @ControllerAdvice with @ResponseBody so return values are serialized to JSON automatically.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

A Consistent Error Response Body

Returning a raw string is rarely enough. Clients want a structured, predictable JSON body they can parse.

Define a small error response record that every handler returns. This is plain Java, no framework needed, so it is fully standalone.

Spring serializes this record to JSON when returned from a @RestControllerAdvice method.

import java.time.Instant;

public record ApiError(
        Instant timestamp,
        int status,
        String error,
        String message,
        String path) {
}

public class Demo {
    public static void main(String[] args) {
        ApiError err = new ApiError(
                Instant.parse("2026-01-01T10:15:30Z"),
                404,
                "Not Found",
                "Product 42 not found",
                "/products/42");
        System.out.println(err);
    }
}

Returning Structured Errors with ResponseEntity

Now combine the ApiError record with your global handler. Build a ResponseEntity that carries both the correct status code and the structured body.

Use the injected HttpServletRequest to capture the request path, which is helpful for debugging on the client side.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ProductNotFoundException ex, HttpServletRequest request) {

        ApiError error = new ApiError(
                Instant.now(),
                HttpStatus.NOT_FOUND.value(),
                HttpStatus.NOT_FOUND.getReasonPhrase(),
                ex.getMessage(),
                request.getRequestURI());

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Mapping Status with @ResponseStatus

If a handler always returns the same status and you do not need custom headers, you can skip ResponseEntity entirely.

Annotate the handler method with @ResponseStatus(...) and return the body directly. Spring applies the status code for you.

This keeps simple handlers concise, but reach for ResponseEntity when you need dynamic status codes or headers.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError handleNotFound(ProductNotFoundException ex, HttpServletRequest req) {
        return new ApiError(Instant.now(), 404, "Not Found",
                ex.getMessage(), req.getRequestURI());
    }
}

Handling Validation Errors

When a @Valid request body fails Bean Validation, Spring throws MethodArgumentNotValidException. By default the JSON response is verbose and noisy.

Override it in your advice to return a clean map of field errors. Each FieldError carries the offending field name and the validation message.

@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
    Map<String, String> errors = new HashMap<>();
    for (FieldError fieldError : ex.getBindingResult().getFieldErrors()) {
        errors.put(fieldError.getField(), fieldError.getDefaultMessage());
    }
    return errors;
}

One Handler for Many Exceptions

@ExceptionHandler accepts an array of exception classes, so a single method can handle several related types that map to the same status.

This avoids duplicate code when, say, several distinct "bad input" exceptions should all become 400 Bad Request.

@ExceptionHandler({
        IllegalArgumentException.class,
        IllegalStateException.class,
        ConstraintViolationException.class
})
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ApiError handleBadRequest(RuntimeException ex, HttpServletRequest req) {
    return new ApiError(Instant.now(), 400, "Bad Request",
            ex.getMessage(), req.getRequestURI());
}

Exception Resolution Order

When an exception is thrown, Spring picks the most specific matching @ExceptionHandler.

An exact-type handler wins over a handler for its superclass.
Local handlers in the controller take precedence over global ones in @ControllerAdvice.
If two handlers are equally specific, Spring raises an ambiguity error at startup.

This ordering lets you provide a broad fallback while still overriding specific cases.

A Safe Catch-All Fallback

Always provide a last-resort handler for Exception.class. It catches anything you did not explicitly map and prevents internal details from leaking.

Return a generic 500 Internal Server Error with a safe message, and log the real exception server-side for investigation.

Never put the raw exception message or stack trace into the client response for unexpected errors.

@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ApiError handleAny(Exception ex, HttpServletRequest req) {
    log.error("Unhandled exception at {}", req.getRequestURI(), ex);
    return new ApiError(Instant.now(), 500, "Internal Server Error",
            "An unexpected error occurred", req.getRequestURI());
}

Scoping and Extending the Framework Base

You can scope an advice to a subset of controllers using attributes like @RestControllerAdvice(basePackages = "com.shop.api") or assignableTypes = {...}. Unscoped advice applies everywhere.

For full control over Spring MVC's built-in exceptions (missing parameters, unreadable bodies, unsupported media types), extend ResponseEntityExceptionHandler and override its protected methods. It already declares handlers for the standard MVC exceptions.

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ProductNotFoundException ex, HttpServletRequest req) {
        ApiError error = new ApiError(Instant.now(), 404, "Not Found",
                ex.getMessage(), req.getRequestURI());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Quick Check

You have a REST API. You want validation errors and not-found errors to produce consistent JSON bodies and correct status codes across every controller, in one place. What is the idiomatic Spring Boot approach?

Recap

You learned how to centralize exception handling in Spring Boot:

@ExceptionHandler maps an exception type to an HTTP response; alone it is controller-local.
@RestControllerAdvice registers handlers globally and serializes return values to JSON.
Return a consistent error record (status, message, path, timestamp) for predictable clients.
Use ResponseEntity for dynamic status/headers, or @ResponseStatus for fixed ones.
Handle MethodArgumentNotValidException for clean validation errors, group related exceptions, and always add an Exception.class catch-all that hides internals.

The result is consistent, secure, and maintainable error responses across your whole API.

Frequently asked questions

Is the “Global Exception Handling with @ControllerAdvice” lesson free?

Yes — the full text of “Global Exception Handling with @ControllerAdvice” is free to read here on the web, and the Spring Boot 4 Complete Guide course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Complete Guide course, upgrade to CoddyKit PRO.

What will I learn in “Global Exception Handling with @ControllerAdvice”?

Centralize exception translation into clean HTTP responses using @ExceptionHandler and @ControllerAdvice. You practise Spring Boot 4 Complete Guide with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Complete Guide?

No prior experience is required. Spring Boot 4 Complete Guide on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Global Exception Handling with @ControllerAdvice” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Complete Guide lesson?

Yes. Every Spring Boot 4 Complete Guide lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Bean Validation Constraints and Constraint Groups
Building Custom Constraint Annotations
Global Exception Handling with @ControllerAdvice
RFC 7807 Problem Detail Responses

← Back to Spring Boot 4 Complete Guide