Spring Boot Exception Handling: @ControllerAdvice, @ExceptionHandler, ErrorAttributes

Every REST API crashes eventually. A database connection drops, a validation check fails, an unexpected null pointer bubbles up. What separates professional APIs from amateur ones is not whether they fail, but how they handle failure. Spring Boot gives you a powerful toolkit for exception handling, and in this post, I will walk you through every piece of it.

Why Exception Handling Matters

Introduction

Exception handling in Spring Boot turns failures into consistent, useful HTTP responses instead of leaking implementation details or leaving clients to interpret arbitrary errors. This guide covers controller-level and global handlers, response formats, validation failures, exception mapping, logging, and the trade-offs between local recovery and centralized handling.

The Exception Handling Flow

Understanding how Spring Boot processes exceptions is essential before diving into the specific annotations.

graph TD
    A[HTTP Request] --> B{Controller Method}
    B -->|Success| C[Return Response]
    B -->|Throws Exception| D[DispatcherServlet]
    D --> E["@ExceptionHandler Methods"]
    E --> F["@ControllerAdvice Global Handler"]
    F --> G{"Exception Type Match?"}
    G -->|Yes| H[Handle Exception]
    G -->|No| I[Base Exception Handlers]
    H --> J[ErrorAttributes Applied]
    I --> J
    J --> K[HTTP Response]
    C --> K

When an exception is thrown inside a controller, Spring’s DispatcherServlet catches it and searches for a matching @ExceptionHandler method. If the controller does not define one, the search expands to any @ControllerAdvice bean in the application context. The matched handler processes the exception, optionally modifies the response using ErrorAttributes, and returns the final HTTP response.

@ExceptionHandler: Per-Controller Control

The @ExceptionHandler annotation lets you define exception handling logic directly inside a controller. This works well for controller-specific error responses.

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userRepository.findById(id)
            .orElseThrow(() -> new UserNotFoundException(id));
    }

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException ex) {
        ErrorResponse error = new ErrorResponse(
            "USER_NOT_FOUND",
            ex.getMessage(),
            HttpStatus.NOT_FOUND.value()
        );
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

The method signature of @ExceptionHandler is flexible. Spring automatically injects the thrown exception, the HTTP request, and even the WebRequest if you declare them as parameters.

When to Use @ExceptionHandler

• Controller-specific error responses that do not apply elsewhere
• Keeping error handling close to the code that produces the errors
• Quick prototyping before extracting to a global handler

When NOT to Use @ExceptionHandler

• Business exceptions that multiple controllers need to handle the same way
• When you find yourself copying the same handler method across controllers
• For exceptions that should be handled uniformly across the entire API

Copying handler methods across controllers is a maintenance nightmare. If you need to change the error format in one place, you have to change it everywhere.

@ControllerAdvice: Global Exception Handling

The @ControllerAdvice annotation transforms any bean into a global exception handler. All @ExceptionHandler methods in that class become applicable to every controller in the application.

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ApiError> handleUserNotFound(UserNotFoundException ex) {
        ApiError error = new ApiError(
            "USER_NOT_FOUND",
            ex.getMessage(),
            Instant.now()
        );
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException ex) {
        List<String> details = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(FieldError::getDefaultMessage)
            .toList();

        ApiError error = new ApiError(
            "VALIDATION_ERROR",
            "Request validation failed",
            Instant.now(),
            details
        );
        return ResponseEntity.badRequest().body(error);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleGeneric(Exception ex) {
        // Log the actual exception, never expose it
        log.error("Unhandled exception", ex);
        ApiError error = new ApiError(
            "INTERNAL_ERROR",
            "An unexpected error occurred",
            Instant.now()
        );
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }
}

Selective Application with Attributes

@ControllerAdvice is powerful, but sometimes you want it to apply only to specific controllers or packages.

// Apply only to controllers in this package
@ControllerAdvice("com.example.api.controllers")

// Apply only to controllers annotated with @RestController
@ControllerAdvice(annotations = RestController.class)

// Apply only to specific controller classes
@ControllerAdvice(assignableTypes = {UserController.class, OrderController.class})

This granular control is useful in large applications where different modules need different error handling strategies.

@ResponseStatus: Declarative HTTP Status Codes

The simplest way to set an HTTP status on an exception is annotating the exception class itself with @ResponseStatus.

@ResponseStatus(HttpStatus.NOT_FOUND)
public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(Long id) {
        super("User with id " + id + " not found");
    }
}

When this exception is thrown and not caught by any @ExceptionHandler, Spring automatically returns a 404 with an empty response body. It works, but it is limited. You cannot add a custom body, log the exception, or apply any additional logic.

Combining @ResponseStatus with @ExceptionHandler

A better pattern is using @ResponseStatus purely to declare intent on the exception class while handling the actual response construction in @ControllerAdvice.

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
    private final String resourceName;
    private final String fieldName;
    private final Object fieldValue;

    public ResourceNotFoundException(String resourceName, String fieldName, Object fieldValue) {
        super(String.format("%s not found with %s: '%s'", resourceName, fieldName, fieldValue));
        this.resourceName = resourceName;
        this.fieldName = fieldName;
        this.fieldValue = fieldValue;
    }
    // getters
}

This separation of concerns keeps your exception classes focused on data while the handler focuses on response formatting.

Customizing Error Responses with ErrorAttributes

ErrorAttributes controls what data appears in the default error response. The default implementation includes timestamp, status, error, message, and path. You can customize or extend this.

Extending DefaultErrorAttributes

@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
        Map<String, Object> errorAttributes = super.getErrorAttributes(webRequest, options);

        // Add custom fields
        errorAttributes.put("correlationId", UUID.randomUUID().toString());
        errorAttributes.put("version", "v1");

        // Remove fields you do not want to expose
        errorAttributes.remove("trace");

        return errorAttributes;
    }
}

Creating a Fully Custom ErrorAttributes Implementation

@Component
public class CustomErrorAttributes implements ErrorAttributes {

    private final ErrorLoggingService errorLoggingService;

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
        Throwable exception = getError(webRequest);

        Map<String, Object> errorAttributes = new HashMap<>();
        errorAttributes.put("timestamp", Instant.now().toString());
        errorAttributes.put("status", getStatus(webRequest).value());
        errorAttributes.put("error", getStatus(webRequest).getReasonPhrase());
        errorAttributes.put("message", exception != null ? exception.getMessage() : "No message");
        errorAttributes.put("path", webRequest.getDescription(false).replace("uri=", ""));

        if (options.isIncluded(Include.STACK_TRACE)) {
            // Only include stack trace in development
            if (environment.getActiveProfiles().contains("dev")) {
                errorAttributes.put("trace", getStackTrace(exception));
            }
        }

        // Always log for correlation
        if (exception != null) {
            String correlationId = errorLoggingService.log(exception);
            errorAttributes.put("correlationId", correlationId);
        }

        return errorAttributes;
    }

    @Override
    public Throwable getError(WebRequest webRequest) {
        return (Throwable) webRequest.getAttribute("javax.servlet.error.exception", SCOPE_REQUEST);
    }

    private HttpStatus getStatus(WebRequest request) {
        Integer status = (Integer) request.getAttribute("javax.servlet.error.status_code", SCOPE_REQUEST);
        return status != null ? HttpStatus.valueOf(status) : HttpStatus.INTERNAL_SERVER_ERROR;
    }
}

Register your custom ErrorAttributes by declaring it as a @Component bean. Spring Boot’s ErrorMvcAutoConfiguration will automatically pick it up.

Failure Scenarios

Even with solid exception handling in place, things can still go wrong. Here are the failure scenarios you need to anticipate.

Handler Throws an Exception

If your @ExceptionHandler method itself throws an exception, Spring falls back to its default error handling. This creates a confusing situation where the original error is lost.

Mitigation: Wrap your handler logic in try-catch and have a fallback that returns a safe generic error.

@ExceptionHandler(Exception.class)
public ResponseEntity<ApiError> handleSafe(Exception ex) {
    try {
        // Risky processing
        return processException(ex);
    } catch (Exception inner) {
        log.error("Error in exception handler", inner);
        return ResponseEntity.status(500).body(ApiError.generic());
    }
}

ResponseStatusException Loses Custom Body

ResponseStatusException is the programmatic equivalent of @ResponseStatus, but it does not automatically work with @ControllerAdvice exception matching.

// This will NOT be caught by @ExceptionHandler(ResponseStatusException.class)
// if it was thrown from within a @ExceptionHandler itself
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "User not found");

Mitigation: Use custom exception classes instead of ResponseStatusException for anything that needs centralized handling.

Circular Exception Handling

If handler A throws exception B, and handler B throws exception A, you get a stack overflow.

Mitigation: Never throw exceptions from within @ExceptionHandler methods. Always convert them to ResponseEntity returns.

Missing Handler for Common Exceptions

MethodArgumentNotValidException, HttpMessageNotReadableException, and MissingServletRequestParameterException are thrown by Spring MVC automatically. If you do not handle them, clients get opaque 400 errors with no useful details.

Mitigation: Add handlers for these common validation exceptions in your global handler.

When to Use / When NOT to Use

When to Use @ExceptionHandler (Per-Controller)

Use @ExceptionHandler when an error response is specific to one controller and does not make sense anywhere else. If a particular controller needs to format an exception differently because the consumers of that endpoint expect a unique error structure, keep it local. This approach also works well during early prototyping before you know what the global pattern should look like.

When NOT to Use @ExceptionHandler (Per-Controller)

As soon as you find yourself copying the same @ExceptionHandler method to multiple controllers, refactor to @ControllerAdvice. Duplicated handler code is a maintenance liability — when the error format needs to change, you have to update every copy. If the same exception type needs to be handled the same way across multiple endpoints, that is a signal to move it global.

When to Use @ControllerAdvice (Global)

Use @ControllerAdvice for exceptions that make sense to handle uniformly across the entire API — business exceptions like UserNotFoundException, validation errors from MethodArgumentNotValidException, or any error format that should be consistent regardless of which controller originated the request.

When to Use @ResponseStatus on Exception Classes

Use @ResponseStatus on custom exception classes when you need a specific HTTP status code and nothing more. It is a zero-code way to map an exception to a status. Avoid it when you need a custom response body, when you want to log the exception, or when the error response depends on context that only a handler method can provide.

When to Use ErrorAttributes Customization

Use ErrorAttributes when you need every error response — including those from Spring’s default BasicErrorController — to follow a consistent structure across your entire API. If you want all clients to receive a uniform error envelope with fields like timestamp, status, error, message, and correlationId, customize ErrorAttributes rather than relying on per-handler construction.

When to Use ErrorController Implementation

Use a custom ErrorController when you need full control over the error page rendering or when the default JSON error format does not meet your needs at all. This is a lower-level approach than ErrorAttributes and is rarely needed.

Trade-off Table

Approach	Pros	Cons
@ExceptionHandler per controller	Simple, local reasoning	Code duplication across controllers
@ControllerAdvice global	Single place to maintain	May need splitting in large apps
@ResponseStatus on exception	Declarative, zero code	No custom body, limited logic
ErrorAttributes customization	Consistent error format	Involves Spring internals
ErrorController implementation	Full control over error page	More code, easier to get wrong

Security Considerations

This section is non-negotiable for production systems.

Never Leak Stack Traces

The default Spring Boot error page includes the full stack trace in development. If that page ever reaches a production client, you have disclosed your entire class hierarchy, library versions, and internal logic.

@Component
public class ProductionErrorAttributes extends DefaultErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest request, ErrorAttributeOptions options) {
        Map<String, Object> attrs = super.getErrorAttributes(request, options);

        // Never expose trace in production
        if (!environment.getActiveProfiles().contains("dev")) {
            attrs.remove("trace");
            attrs.remove("errors");
        }

        return attrs;
    }
}

Validate Error Message Content

If you pass user input directly into error messages, you open the door to log injection attacks. A malicious user submits a request with X-Requested-With: <script>alert(1)</script> and if you echo that header into a log-prefixed error message, you have a cross-site scripting vector.

@ExceptionHandler(BadRequestException.class)
public ResponseEntity<ApiError> handleBadRequest(BadRequestException ex) {
    String sanitized = sanitize(ex.getMessage()); // Strip HTML/script tags
    return ResponseEntity.badRequest().body(new ApiError("BAD_REQUEST", sanitized));
}

Do Not Expose Internal Paths

The path field in error attributes reveals your internal URL structure. In some deployments, this alone can help an attacker map your application’s internal routing.

@Override
public Map<String, Object> getErrorAttributes(WebRequest webRequest, ErrorAttributeOptions options) {
    Map<String, Object> attrs = super.getErrorAttributes(webRequest, options);
    // Replace path with a generic indicator in production
    if (!environment.getActiveProfiles().contains("dev")) {
        attrs.put("path", "redacted");
    }
    return attrs;
}

Common Pitfalls / Anti-Patterns

Handling the wrong exception type. Make sure your @ExceptionHandler parameter matches the actual exception being thrown. Generic Exception.class handlers should always be last in the chain.

Ignoring the HTTP method context. A 404 on a GET request has different semantics than a 404 on a DELETE. Your error messages should reflect what failed, not just that it failed.

Returning null from a handler. If your handler returns null, Spring treats it as if no handler matched and continues searching. This leads to confusing behavior and potentially recursive handler searches.

Forgetting to mark exceptions as unchecked. Checked exceptions require throws declarations and clutter your controller signatures. Extend RuntimeException for most business exceptions so handlers can catch them without ceremony.

Not testing your error paths. Unit tests that only exercise the happy path miss the most critical part of your API. Write tests that verify each exception handler returns the correct status code and body.

Observability Checklist

A well-observed API lets you diagnose production issues in minutes, not hours.

• Every exception handler logs the exception with a correlation ID
• Error responses include the correlation ID so clients can report it
• Metric counter incremented for each error type
• Alerting configured for spike in 5xx errors
• Alerting configured for spike in 4xx client errors (may indicate abuse)
• Health check endpoint reports degraded state when error rate is high
• Distributed trace ID propagated through error logging
• Error attributes include request ID for log correlation

@ExceptionHandler(Exception.class)
public ResponseEntity<ApiError> handleLoggedException(Exception ex, WebRequest request) {
    String correlationId = UUID.randomUUID().toString();
    String traceId = request.getHeader("X-Trace-Id");

    log.error("Unhandled exception. correlationId={}, traceId={}, exception={}",
        correlationId, traceId, ex.getClass().getName(), ex);

    metrics.increment("error.unhandled", "type", ex.getClass().getSimpleName());

    return ResponseEntity.status(500).body(
        new ApiError("INTERNAL_ERROR", "An error occurred. Reference: " + correlationId)
    );
}

Quick Recap Checklist

• Use @ControllerAdvice for global exception handling across all controllers
• Reserve @ExceptionHandler for controller-specific cases only
• Separate exception classes from response formatting logic
• Customize ErrorAttributes for consistent error response structure
• Never expose stack traces, internal paths, or class names in production
• Add correlation IDs to every error response
• Handle Spring MVC’s automatic exceptions (MethodArgumentNotValidException, etc.)
• Write handler methods that never throw exceptions
• Test every error path with unit tests
• Log exceptions server-side with enough context to reproduce the issue

Related Posts

• Java Custom Exceptions — Learn how to design exception classes that carry meaningful context
• Java Exception Best Practices — Broader patterns for working with exceptions in Java
• RESTful API Design — Design principles that complement robust error handling
• API Gateway Patterns — Where exception handling fits in your overall API architecture

Interview Questions

Further Reading

These deep dives cover advanced topics that build on the exception handling foundation covered above.

• Validation Exception Handling — MethodArgumentNotValidException and ConstraintViolationException have different sources (body vs parameter validation). Understanding which validator fires when helps you write precise handlers for each case.
• Exception Handling in Reactive Streams — WebFlux uses a different exception handling model than MVC. WebExceptionHandler replaces @ExceptionHandler in reactive applications, and the propagation semantics are different.
• Integration with API Gateways — When your Spring Boot service sits behind a gateway like Spring Cloud Gateway or Zuul, error handling crosses process boundaries. The gateway may transform your error response, so design for it.
• RFC 7807 Problem Details — This standard defines a structured error response format (type, title, status, detail, instance). Spring supports it natively with ProblemDetail and ErrorResponse.
• Internationalization of Error Messages — Use Spring’s MessageSource to return localized error messages. Users in different locales should see errors in their language, not just English.
• Exception Handling and Transaction Rollback — By default, @ExceptionHandler methods do not trigger transaction rollback. If your handler runs within a transaction and you need rollback behavior, use @Transactional(rollbackFor = …).
• Testing Exception Handlers — Use @WebMvcTest with MockMvc to test handlers in isolation. MockMvc.perform(get(“/users/1”)).andExpect(status().isNotFound()) verifies the handler response without spinning up the full application context.
• Centralized Logging with Correlation IDs — Propagate a X-Correlation-ID header from API Gateway through to your logs. Every exception log should include this ID so you can trace a request across service boundaries.

Conclusion

Spring Boot’s exception handling toolkit gives you everything you need to build APIs that fail gracefully. The key layers are @ExceptionHandler for per-controller cases, @ControllerAdvice for global consistency, ErrorAttributes for response structure, and @ResponseStatus for declarative status codes on exception classes. Combine these tools with proper logging, correlation IDs, and a security-first mindset where stack traces and internal paths never reach clients.

A well-designed exception handling strategy means your API always returns predictable, documented error responses — regardless of what goes wrong internally. That predictability is what separates production-grade APIs from prototypes.