MethodArgumentNotValidException in Spring Boot

In Spring Boot applications, especially those exposing RESTful APIs, data validation is a crucial aspect to ensure the integrity and safety of the system. 

Spring Boot provides a handy way to validate request payloads using annotations and MethodArgumentNotValidException is thrown when these validations fail. In this post, we will dive deep into understanding this exception, its causes, and the best strategies to handle it. 

What is MethodArgumentNotValidException? 

The MethodArgumentNotValidException is thrown by Spring Boot when validation on an argument annotated with @Valid fails. This typically happens during the deserialization process when a client sends a request to a Spring REST endpoint. 


Invalid Request Payload: This is the most common cause. For instance, when a client sends data that doesn't meet the validation criteria defined in the DTO (Data Transfer Object). 

Binding Errors: When the expected format of an incoming request body doesn't match the expected format. 

Reproducing the Exception

Consider this simple DTO with validation annotations:

public class UserDTO {
    @NotBlank(message = "Name should not be blank")
    private String name;

    @Min(value = 18, message = "Age should be greater than 18")
    private Integer age;

    // getters and setters

Now, consider an endpoint that accepts this DTO:

public ResponseEntity<String> createUser(@Valid @RequestBody UserDTO user) {
    // logic to create user
    return new ResponseEntity<>("User created successfully", HttpStatus.CREATED);

If you send a request with a blank name or an age less than 18, the application will throw MethodArgumentNotValidException

Handling the Exception

To handle this exception and return a proper message to the client, you can use Spring's @ControllerAdvice:

public class GlobalExceptionHandler {

    public ResponseEntity<Object> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach(error -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);

This exception handler captures the exception and maps the field errors to a map, which is then returned as a response. This way, the client can get a clear understanding of which fields failed validation and why. 

Check out the complete example: Spring Boot Exception Handling for REST APIs


MethodArgumentNotValidException is a powerful feature in Spring Boot that helps developers ensure the quality and correctness of incoming data. Instead of handling validation manually, Spring Boot provides a declarative way to specify constraints on your data models. Properly handling this exception provides clients with clear feedback on the nature of the validation failure, thus enhancing the API's usability.

Related Spring Exceptions Posts