Spring Boot Validation — 2GB Payload Crashes Without @Valid

I've been debugging Spring Boot apps since 1.5.2.RELEASE, and I've seen production meltdowns that trace back to a single missing annotation: @Valid. The most memorable was a SaaS billing service that accepted a 2.1GB JSON payload from a misconfigured client. No @Valid on the controller. No @Size on the List field. The app tried to deserialize the entire monstrosity into memory, hit the heap limit, and OOM-killed the pod. The billing pipeline went down for 45 minutes. The root cause? A junior dev forgot @Valid on a single @RequestBody parameter. That's it. One annotation. 45 minutes of downtime. In this tutorial, I'll show you exactly how @Valid works under the hood, why skipping it is dangerous, and how to build bulletproof validation for REST APIs that handle anything from tiny forms to massive payloads. We'll cover JSR-380 Bean Validation, custom validators, group sequences, and production patterns like logging validation failures without exposing internals. By the end, you'll never ship a controller without @Valid again.

Setting Up the Project

Let's start with a Spring Boot 3.2 project using Maven. We'll add the validation starter which pulls in Hibernate Validator 8.0 (the reference implementation of JSR-380). Create a new project with spring-boot-starter-web and spring-boot-starter-validation. In your pom.xml, include:

org.springframework.boot spring-boot-starter-validation

This starter automatically configures a LocalValidatorFactoryBean and registers it with Spring MVC. No extra configuration needed. For Java 17+, we'll use records as DTOs — they're immutable and perfect for validation. Here's a simple Invoice record with constraints: @NotNull on the id, @NotBlank on the customerEmail, @Positive on the amount, and @Size(max = 10) on lineItems to prevent huge lists. We'll also add a custom error message for each constraint. The key is that without @Valid on the controller parameter, none of these constraints fire. Spring just deserializes the JSON and passes the object straight to your method.

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

What the Official Docs Won't Tell You

The Spring Boot reference docs show you how to use @Valid on a single @RequestBody parameter. They don't tell you that if you forget it, your app will silently accept any payload — including a 2GB JSON array that causes OOM. They don't tell you that @Valid only triggers cascading validation on nested objects if you also annotate the nested fields with @Valid. They don't tell you that validation errors by default return a 400 with a stack trace in the response body, leaking internal class names. They don't tell you that @Valid and @Validated are not interchangeable: @Valid is JSR-380 standard, @Validated is Spring's extension that enables validation groups. Use @Validated on the class level for method-level validation (like @PathVariable), and @Valid on parameters. Also, the docs gloss over the fact that validation runs AFTER Jackson deserialization. If you have a @Size(max = 100) on a List, Jackson still allocates the entire array before validation rejects it. To prevent OOM, you need to set spring.jackson.deserialization.max-array-length in application.properties. That's a Jackson-level safeguard that runs before validation.

# Jackson-level limit to prevent huge arrays from being deserialized
spring.jackson.deserialization.max-array-length=10000
# Servlet container max request size
spring.servlet.multipart.max-request-size=10MB
# Log validation errors without exposing stack traces
server.error.include-stacktrace=never

Creating a Validated DTO with Records

Java 16+ records are perfect for DTOs — they're immutable, concise, and support Bean Validation annotations out of the box. Here's an Invoice record with constraints on every field. Notice the @Valid annotation on the List field: this enables cascading validation, meaning each LineItem in the list is also validated against its own constraints. Without @Valid on the nested field, the line items are ignored. Also note the use of @NotEmpty on the list: this ensures the list is not null AND has at least one element. @Size(max = 10) limits the list to 10 items. For the amount field, @PositiveOrZero allows zero but not negative. We use @Email on customerEmail, but be careful — @Email only checks format, not whether the email actually exists. For production, you'd want a custom validator that calls an email verification service. The record constructor automatically validates fields during deserialization IF @Valid is present on the controller parameter. This is a compile-time guarantee of data integrity.

import jakarta.validation.Valid;
import jakarta.validation.constraints.*;
import java.math.BigDecimal;
import java.util.List;

public record Invoice(
    @NotNull(message = "Invoice ID is required")
    Long id,

    @NotBlank(message = "Customer email is required")
    @Email(message = "Invalid email format")
    String customerEmail,

    @PositiveOrZero(message = "Amount must be zero or positive")
    BigDecimal amount,

    @NotEmpty(message = "At least one line item is required")
    @Size(max = 10, message = "Maximum 10 line items allowed")
    @Valid  // <-- enables cascading validation
    List<LineItem> lineItems
) {}

Building a Controller with @Valid

Here's the controller that caused our production incident. The method createInvoice accepts an @RequestBody Invoice without @Valid. Spring Boot will deserialize the JSON into an Invoice record, but NONE of the validation constraints on Invoice or LineItem will fire. The method receives whatever Jackson produces — even if fields are null or the list has 2 million items. To fix this, add @Valid before the @RequestBody parameter. Now Spring MVC will call the Validator before executing the method. If validation fails, a MethodArgumentNotValidException is thrown, which we can handle globally. Notice we also use @Validated on the class level — this enables method-level validation for other parameters like @PathVariable or @RequestParam. But for @RequestBody, @Valid is the standard. Also note the use of BindingResult parameter: if you add BindingResult immediately after @Valid, you can handle validation errors manually. But in production, use global exception handling instead — it's cleaner and consistent.

import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

@Validated
@RestController
@RequestMapping("/api/invoices")
public class InvoiceController {

    @PostMapping
    public ResponseEntity<Invoice> createInvoice(
            @Valid @RequestBody Invoice invoice) {
        // invoice is guaranteed valid here
        return ResponseEntity.ok(invoice);
    }
}

Global Exception Handling for Validation Errors

Without a global exception handler, a validation failure returns a 400 with a stack trace and internal class names like 'jakarta.validation.ConstraintViolationException'. That's a security risk. Use @ControllerAdvice to catch MethodArgumentNotValidException (for @Valid on parameters) and ConstraintViolationException (for @Validated on class-level). Return a consistent JSON error response with field-level messages. Here's a handler that extracts field errors and returns a map of field names to error messages. We also log the validation failure at WARN level for debugging, but never include the full stack trace in the response. For production, you might want to include a correlation ID so you can trace the request in logs. Also handle HttpMessageNotReadableException for malformed JSON — this catches cases where Jackson fails to deserialize. The key is to never expose internal implementation details in error responses.

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.Map;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationErrors(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error ->
            errors.put(error.getField(), error.getDefaultMessage()));
        return ResponseEntity.badRequest().body(errors);
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<Map<String, String>> handleConstraintViolation(
            ConstraintViolationException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getConstraintViolations().forEach(violation ->
            errors.put(violation.getPropertyPath().toString(),
                       violation.getMessage()));
        return ResponseEntity.badRequest().body(errors);
    }
}

Custom Validators for Business Rules

Built-in constraints like @NotNull and @Size cover basic cases, but real-world apps need business rule validation. For example, an invoice's total amount must equal the sum of its line item amounts. Create a custom annotation @InvoiceTotalValid and a validator class that implements ConstraintValidator. The validator receives the Invoice record and can access all fields. If the total doesn't match, return false and a message. Register the annotation on the Invoice record itself. This is class-level validation, which runs after all field-level validations pass. Also note that custom validators can inject Spring beans (like a repository) if you implement ApplicationContextAware or use @Autowired in the validator. But be careful: validators are singletons, so inject only stateless beans. For stateful operations, use a separate service. Custom validators are powerful but can be slow — avoid database calls in validators if possible.

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import java.math.BigDecimal;

public class InvoiceTotalValidator
        implements ConstraintValidator<InvoiceTotalValid, Invoice> {

    @Override
    public boolean isValid(Invoice invoice,
                           ConstraintValidatorContext context) {
        if (invoice.lineItems() == null || invoice.amount() == null) {
            return true; // other validators handle null
        }
        BigDecimal sum = invoice.lineItems().stream()
                .map(LineItem::total)
                .reduce(BigDecimal.ZERO, BigDecimal::add);
        return sum.compareTo(invoice.amount()) == 0;
    }
}

Validation Groups for Partial Updates

In REST APIs, POST (create) and PUT (update) often have different validation rules. For example, during create, the id field must be null (auto-generated). During update, id must be present. Use validation groups to handle this. Define marker interfaces: OnCreate and OnUpdate. Annotate fields with @NotNull(groups = OnUpdate.class) and @Null(groups = OnCreate.class). In the controller, use @Validated(OnCreate.class) on the parameter for POST and @Validated(OnUpdate.class) for PUT. Note: @Validated is Spring's annotation for group-based validation — you cannot use @Valid with groups. Also, @Validated on the controller method replaces @Valid. This is a common point of confusion. Groups are powerful but add complexity. Only use them when you have genuinely different validation rules between operations. For simple cases, use separate DTOs for create and update.

public record InvoiceWithGroups(
    @Null(groups = OnCreate.class,
          message = "ID must be null for new invoice")
    @NotNull(groups = OnUpdate.class,
             message = "ID is required for update")
    Long id,

    @NotBlank(groups = {OnCreate.class, OnUpdate.class})
    String customerEmail
) {}

// Controller:
@PostMapping
public ResponseEntity<?> create(
    @Validated(OnCreate.class) @RequestBody InvoiceWithGroups inv) { ... }

@PutMapping("/{id}")
public ResponseEntity<?> update(
    @Validated(OnUpdate.class) @RequestBody InvoiceWithGroups inv) { ... }

Testing Validation with JUnit 5 and MockMvc

Unit tests for validation are non-negotiable. Use MockMvc to send invalid payloads and assert the response status and error messages. Here's a test that sends an invoice with a blank email and a negative amount. The test expects HTTP 400 and specific error messages. Use @WebMvcTest to load only the controller layer. Mock the service layer if needed. For the test to work, the ValidationAutoConfiguration must be active — it is by default with @WebMvcTest. Also test edge cases: null body, empty list, oversized list. Don't forget to test the happy path too — a valid payload should return 200. For integration tests, use @SpringBootTest with a random port and TestRestTemplate. This catches configuration issues like missing validation starter. In CI, run validation tests as part of every build. We once pushed a change that accidentally removed @Valid from a controller — the tests caught it immediately.

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(InvoiceController.class)
class InvoiceControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void shouldReturn400WhenEmailBlank() throws Exception {
        String invalidJson = """
            {"id":1,"customerEmail":"","amount":100}
            """;
        mockMvc.perform(post("/api/invoices")
                .contentType(MediaType.APPLICATION_JSON)
                .content(invalidJson))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.customerEmail")
                    .value("Customer email is required"));
    }
}