Problem Spring Web

The library uses 'Advice Traits' to map specific exceptions to Problem details. You can implement the ProblemHandling interface in a @ControllerAdvice class to get a default set of handlers, or implement specific traits individually to pick and choose which errors you want to handle.

A typical implementation uses ProblemHandling to cover all standard web errors:

@ControllerAdvice
class ExceptionHandling implements ProblemHandling {

}

The library uses 'Advice Traits' to handle specific error scenarios. You can implement these traits individually or group them by implementing interfaces like ProblemHandling.

Important WebFlux Note: In WebFlux, if a request handler is never called (e.g., a 404 or 405 error), @ControllerAdvice is not triggered. To handle these cases, you must register a ProblemExceptionHandler with high precedence using @Order(-2) to override default Spring Boot error handlers.

@Bean
@Order(-2) // Must precede WebFluxResponseStatusExceptionHandler and Spring Boot's ErrorWebExceptionHandler
public WebExceptionHandler problemExceptionHandler(ObjectMapper mapper, ProblemHandling problemHandling) {
    return new ProblemExceptionHandler(mapper, problemHandling);
}

To support CircuitBreakerOpenException from Failsafe, implement the CircuitBreakerOpenAdviceTrait. This will translate open circuit breakers into a 503 Service Unavailable problem response.

@ControllerAdvice
class ExceptionHandling implements ProblemHandling, CircuitBreakerOpenAdviceTrait {

}

Add the following dependencies to your Maven project to use Problem for Spring WebFlux. Ensure you include jackson-datatype-problem to support the problem JSON format.

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-spring-webflux</artifactId>
    <version>${problem-spring-webflux.version}</version>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>jackson-datatype-problem</artifactId>
    <version>0.27.1</version>
</dependency>

Causal chains (showing the nested cause of an error) are disabled by default. To enable them, implement the isCausalChainsEnabled() method in your @ControllerAdvice class that implements ProblemHandling and return true.

@ControllerAdvice
class ExceptionHandling implements ProblemHandling {

    @Override
    public boolean isCausalChainsEnabled() {
        return true;
    }

}

To include stack traces in your application/problem+json responses, configure your ProblemModule with the .withStackTraces() method when registering it with your Jackson ObjectMapper.

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new ProblemModule().withStackTraces());

To handle security-related exceptions (like authentication or access denied) using the Problem format, you must implement SecurityAdviceTrait in a @ControllerAdvice and configure SecurityProblemSupport in your security filter chain.

@ControllerAdvice
class ExceptionHandling implements ProblemHandling, SecurityAdviceTrait {
}

@Configuration
@Import(SecurityProblemSupport.class)
public class SecurityConfiguration {

    @Autowired
    private SecurityProblemSupport problemSupport;

    @Bean
    public SecurityWebFilterChain securityWebFilterChain(final ServerHttpSecurity http) {
        return http.exceptionHandling()
                .authenticationEntryPoint(problemSupport)
                .accessDeniedHandler(problemSupport)
                .and().build();
    }
}

To correctly serialize problem details, register the ProblemModule and ConstraintViolationProblemModule as beans in your Spring configuration.

@Bean
public ProblemModule problemModule() {
    return new ProblemModule();
}

@Bean
public ConstraintViolationProblemModule constraintViolationProblemModule() {
    return new ConstraintViolationProblemModule();
}

To enable NoHandlerFoundAdviceTrait (which produces 404 Not Found), you must configure Spring MVC to throw exceptions when no handler is found and disable resource mapping additions.

spring:
  resources:
    add-mappings: false
  mvc:
    throw-exception-if-no-handler-found: true

If using Spring Boot, you must also exclude ErrorMvcAutoConfiguration:

@EnableAutoConfiguration(exclude = ErrorMvcAutoConfiguration.class)

If you are not using the problem-spring-web-starter module, you must manually register the required Jackson modules with your ObjectMapper to ensure problem details are serialized correctly.

@Bean
public ProblemModule problemModule() {
    return new ProblemModule();
}

@Bean
public ConstraintViolationProblemModule constraintViolationProblemModule() {
    return new ConstraintViolationProblemModule();
}