In-depth Analysis and Solutions for @Valid and @NotBlank Validation Annotations Not Working in Spring Boot

Problem Background and Symptom Description

In Spring Boot application development, data validation is crucial for ensuring API input integrity. Developers often use JSR-380 annotations like @NotBlank and @Pattern, combined with Spring's @Valid or @Validated annotations, to implement automatic validation. However, in practice, these annotations can sometimes fail unexpectedly, allowing invalid data to bypass checks and cause runtime errors or security vulnerabilities.

Consider a typical scenario: a developer builds a REST API to handle contract printing requests. The controller method accepts an UpdatePrintContracts object as the request body, with fields annotated with @NotBlank and @Pattern. During testing, even when blank or malformed data is submitted, no validation exceptions are thrown, and business logic proceeds. This clearly defeats the purpose of validation and requires thorough investigation.

Core Problem Analysis

The causes of validation failure often span multiple levels, including dependency configuration, annotation usage, and regex design. Below is an analysis of the main aspects.

Dependency Configuration Issues: Changes in Spring Boot 2.x

Starting from Spring Boot 2.3, the validation starter (spring-boot-starter-validation) is no longer included by default in the web starter (spring-boot-starter-web). This means that if a project upgrades to version 2.3 or later without explicitly adding the validation dependency, validation annotations will not work. This is a common issue for developers migrating from older versions.

In Maven projects, add the following dependency to pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

In Gradle projects, add this to build.gradle:

implementation 'org.springframework.boot:spring-boot-starter-validation'

Adding only the JSR specification API (e.g., validation-api) is insufficient, as it provides interfaces without an implementation. Hibernate Validator is a common implementation library, and spring-boot-starter-validation integrates it, simplifying configuration.

Annotation Misuse: Confusion Over @Valid Placement

In the provided case, the UpdatePrintContracts class incorrectly uses @Valid annotations on fields. @Valid is applied at the object level to trigger nested validation, not at the field level. For primitive types or collection fields, using @Valid directly on fields is ineffective and may disrupt the validation process.

The correct approach is to add @Valid or @Validated on the controller method parameter to trigger validation of the entire object. For example:

@RequestMapping(value=PATH_PRINT_CONTRACTS, method=RequestMethod.POST)
public ResponseEntity<?> printContracts(@Valid @RequestBody final UpdatePrintContracts updatePrintContracts) throws Exception {
    // Business logic
}

This way, Spring automatically validates the updatePrintContracts object before method execution. If constraints are violated, it throws a MethodArgumentNotValidException, which can be handled by a global exception handler.

Regex Design Flaws: Missing Anchors

The @Pattern annotation validates string formats, but its regex patterns must be designed carefully. In the case, the pattern is "\p{Alnum}{1,30}", intended to match 1 to 30 alphanumeric characters. However, this pattern may match only part of the string, not the entire string, leading to lax validation.

An improved solution is to add anchors ^ (start of string) and $ (end of string) to ensure the whole string conforms:

@Pattern(regexp = "^[\p{Alnum}]{1,30}$")
String isReprint;

This prevents strings like "abc123!!!" from being incorrectly accepted (since "abc123" partially matches).

Solutions and Best Practices

Based on the analysis, resolving validation failures involves the following steps:

1. Check Dependency Configuration: Ensure the project includes the spring-boot-starter-validation dependency, especially in Spring Boot 2.3+.
2. Correct Annotation Usage: Remove @Valid annotations from fields and use @Valid or @Validated only on controller method parameters.
3. Optimize Regex Patterns: Add anchors to @Pattern patterns to ensure full-string matching.
4. Verify Implementation Library: Ensure the classpath includes an implementation library like Hibernate Validator, not just the API.

Example of the corrected UpdatePrintContracts class:

public class UpdatePrintContracts {
    @NotBlank
    @Pattern(regexp = "^[\p{Alnum}]{1,30}$")
    String isReprint;
    
    @NotBlank
    Integer dealerId;
    
    @NotBlank
    @Pattern(regexp = "^[\p{Alnum}]{1,30}$")
    String includeSignatureCoordinates;
    
    @NotBlank
    java.util.List<Integer> contractNumbers;
    
    // Getter and Setter methods
}

Corrected controller method:

@RequestMapping(value=PATH_PRINT_CONTRACTS, method=RequestMethod.POST)
public ResponseEntity<?> printContracts(@Valid @RequestBody final UpdatePrintContracts updatePrintContracts) throws Exception {
    // Execute business logic after validation passes
    Integer cancellationReasons = service.getPDFDetails(updatePrintContracts);
    return ResponseEntity.ok(cancellationReasons);
}

Testing and Validation

Use tools like SoapUI or Postman to test by submitting blank or invalid data. The system should return a 400 Bad Request response with validation error details. Spring Boot handles MethodArgumentNotValidException by default, returning structured error information for debugging.

For example, if the isReprint field is blank, the response might include:

{
    "timestamp": "2023-10-01T12:00:00.000+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "Validation failed for object='updatePrintContracts'. Error count: 1",
    "errors": [
        {
            "field": "isReprint",
            "defaultMessage": "must not be blank"
        }
    ]
}

Conclusion

Data validation in Spring Boot is a powerful feature that requires careful configuration. By ensuring complete dependencies, correct annotation usage, and optimized regex patterns, developers can build robust API validation layers. This article, based on a real-world case, provides a comprehensive guide from problem diagnosis to resolution, helping avoid common pitfalls and improve code quality. During development, it is advisable to refer to Spring official documentation and community resources to stay updated with version changes and adapt to future updates.