Spring Boot Exception Handling

Check these common causes:

1. The advice class is not scanned. It must be in the package of your @SpringBootApplication class or a sub-package.
2. The exception is caught earlier, for example by a try/catch in the service that returns null instead.
3. It was thrown in a filter, such as Spring Security, before the request reached a controller.
4. Another handler matched first: a more specific handler, a local @ExceptionHandler in the controller, or another advice with higher priority.
5. The advice is limited with basePackages or assignableTypes that do not include this controller.

Most security checks happen in filters, before any controller runs, so controller advice never sees them. Customise them in the security configuration instead:

http.exceptionHandling(ex -> ex
        .authenticationEntryPoint((request, response, e) ->            // 401
                response.sendError(HttpServletResponse.SC_UNAUTHORIZED))
        .accessDeniedHandler((request, response, e) ->                 // 403
                response.sendError(HttpServletResponse.SC_FORBIDDEN)));

One exception: AccessDeniedException from @PreAuthorize on a controller method does reach your advice. Make sure your catch-all Exception handler does not turn it into a 500. Add a specific handler that returns 403.

For most Spring applications, use unchecked exceptions that extend RuntimeException:

• Methods do not need throws clauses all the way up the call chain.
• @Transactional rolls back automatically on unchecked exceptions, but not on checked ones by default.
• A global handler deals with them anyway, so forcing every caller to catch them adds no value.

Checked exceptions still make sense in libraries, when the caller can genuinely recover, for example by choosing another file when one is missing.

Many teams simply use 400 for all input problems and 409 for conflicts with existing data. Whatever you choose, be consistent and document it.

Since Spring Framework 6.1 (Spring Boot 3.2), an unknown URL raises NoResourceFoundException, which you can handle like any other exception:

@ExceptionHandler(NoResourceFoundException.class)
public ProblemDetail handleUnknownUrl(NoResourceFoundException ex) {
    return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND,
            "The requested resource does not exist.");
}

If you extend ResponseEntityExceptionHandler, this is already handled for you. On older versions, set spring.mvc.throw-exception-if-no-handler-found=true and spring.web.resources.add-mappings=false, then handle NoHandlerFoundException.

Without configuration, the order is not guaranteed. Set it with @Order; a lower number means higher priority:

@RestControllerAdvice
@Order(Ordered.HIGHEST_PRECEDENCE)
public class PaymentExceptionHandler { ... }

@RestControllerAdvice
@Order(Ordered.LOWEST_PRECEDENCE)
public class GlobalExceptionHandler { ... }   // contains the catch-all

Spring checks the advice classes in order and uses the first one that has a matching handler. Keep the catch-all Exception handler in the lowest-priority class, or it will hide the specific handlers in other classes.

Yes. Limit it by package, by class, or by annotation:

@RestControllerAdvice(basePackages = "com.javabytechie.books.api.admin")
public class AdminExceptionHandler { ... }

@RestControllerAdvice(assignableTypes = {BookController.class, AuthorController.class})
public class CatalogExceptionHandler { ... }

@RestControllerAdvice(annotations = PublicApi.class)
public class PublicApiExceptionHandler { ... }

This helps when one application serves two kinds of clients, for example a public API that must use ProblemDetail and an internal admin API with its own format.

Yes. The exception passes through the transactional service method first, and the transaction is rolled back at that moment. Only afterwards does it reach the controller advice, which turns it into a response.

The opposite case is the trap: if you catch the exception inside the @Transactional method and do not rethrow it, the transaction commits as if nothing went wrong.

No. Controller advice only handles exceptions from web requests. Background methods run on other threads, outside any request:

• @Async methods returning CompletableFuture store the exception in the future; handle it with exceptionally().
• @Async methods returning void need an AsyncUncaughtExceptionHandler.
• @Scheduled methods need their own try/catch, or an error handler on the task scheduler.

Translate them into your own exceptions at the edge of your service. Do not simply pass another service’s status codes through, because they may make no sense to your clients:

public AuthorDto getAuthor(Long id) {
    return restClient.get()
            .uri("/api/authors/{id}", id)
            .retrieve()
            .onStatus(status -> status.value() == 404,
                    (request, response) -> { throw new AuthorNotFoundException(id); })
            .onStatus(HttpStatusCode::is5xxServerError,
                    (request, response) -> { throw new AuthorServiceUnavailableException(); })
            .body(AuthorDto.class);
}

A 404 from the author service means “author not found” to your client. A 500 from it should become a 503 from you, because your service is fine, but a dependency is not.

Messages are for humans and may change. Give each error a stable, machine-readable code that clients can rely on:

ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
problem.setType(URI.create("https://api.javabytechie.com/errors/out-of-stock"));
problem.setProperty("code", "BOOK_OUT_OF_STOCK");
return problem;

A mobile app can then check code == "BOOK_OUT_OF_STOCK" and show its own message, in the user’s language, without breaking when the English text is reworded.

Store messages in messages.properties files and look them up with MessageSource. Spring passes the client’s Locale to the handler, based on the Accept-Language header:

# messages.properties
error.book.notFound=No book exists with id {0}

# messages_hi.properties
error.book.notFound=आईडी {0} वाली कोई किताब नहीं है

@ExceptionHandler(BookNotFoundException.class)
public ProblemDetail handleNotFound(BookNotFoundException ex, Locale locale) {
    String detail = messageSource.getMessage("error.book.notFound", new Object[]{ex.getBookId()}, locale);
    return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, detail);
}

Yes. Exceptions are for exceptional situations. Creating them is relatively costly because Java records the stack trace, and using them for expected outcomes makes code harder to follow.

// Avoid: an exception for a normal "no" answer
try {
    userService.findByEmail(email);
    return true;
} catch (UserNotFoundException ex) {
    return false;
}

// Prefer: ask the question directly
return userRepository.existsByEmail(email);

Throwing BookNotFoundException when a client requests a missing book is fine: it ends the request with an error. Using exceptions to drive loops or ordinary decisions is not.

Always pass the original exception as the cause. Otherwise, the real reason for the failure disappears from your logs:

try {
    return pdfRenderer.render(invoice);
} catch (IOException ex) {
    throw new InvoiceGenerationException("Could not render invoice " + invoice.getId(), ex); // keep ex
}

The log then shows both your message and the original IOException under “Caused by”. This is why the ApplicationException base class in this tutorial has a constructor that accepts a cause.

Spring cannot use your handler, so it falls back to its default error handling. The client usually gets a generic 500 response from the /error endpoint, and the new exception is logged.

Keep handlers simple and safe: no database calls, no remote calls, and careful null handling, for example when ex.getMessage() is null. A handler should never be a new source of failures.

Mostly, yes. @RestControllerAdvice, @ExceptionHandler and ProblemDetail all work in WebFlux, and handlers may return Mono values.

Two differences to know:

• There is no HttpServletRequest; use ServerWebExchange or ServerHttpRequest as a handler parameter instead.
• For errors outside controllers, such as in a WebFilter, implement a WebExceptionHandler.

The reactive base class equivalent to the Spring MVC one is also called ResponseEntityExceptionHandler, but it lives in the org.springframework.web.reactive package.

These errors go straight to Spring Boot’s /error endpoint. Change its JSON by providing your own ErrorAttributes bean:

@Component
public class CustomErrorAttributes extends DefaultErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest request, ErrorAttributeOptions options) {
        Map<String, Object> attributes = super.getErrorAttributes(request, options);
        attributes.put("support", "support@javabytechie.com");
        attributes.remove("error");
        return attributes;
    }
}

Combined with a controller advice, every error, inside or outside controllers, then follows a format you control.

Add pages named after the status code. Spring Boot finds them automatically:

These pages are only used for browser requests that accept HTML. API clients asking for JSON still receive JSON.

All three work. Choose based on what you need to control:

@ExceptionHandler(RateLimitExceededException.class)
public ResponseEntity<ProblemDetail> handleRateLimit(RateLimitExceededException ex) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.TOO_MANY_REQUESTS, ex.getMessage());
    return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
            .header(HttpHeaders.RETRY_AFTER, "60")
            .body(problem);
}

Yes, it is very helpful. When a user reports a problem, the ID leads you straight to the matching log lines across all your services. With Micrometer Tracing on the classpath, the current trace ID is easy to add:

@ExceptionHandler(Exception.class)
public ProblemDetail handleUnexpected(Exception ex) {
    String traceId = Optional.ofNullable(tracer.currentSpan())
            .map(span -> span.context().traceId())
            .orElse("unknown");
    log.error("Unexpected error, traceId={}", traceId, ex);

    ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
    problem.setDetail("An unexpected error occurred.");
    problem.setProperty("traceId", traceId);
    return problem;
}

A trace ID reveals nothing sensitive, so it is safe to share with clients. Without tracing, a random error ID works just as well, as shown in section 10.