Validation and a Global Exception Strategy

In plain words. Validation means "before doing anything, check whether what you were handed is acceptable": is the username empty, does the email contain an @, is the age at least 18? Exception handling means "after something blows up, how do you tell the outside world what actually broke". Together these two chores account for about half the code in a typical endpoint — and neither belongs inside business logic. Rules should hang on fields, and safety nets should live in one place.

Every term, explained once, because the whole article uses them:

• annotation: a label you write in code, starting with @. It does nothing by itself; a framework reads it at runtime and acts. @NotBlank is only a sticker — Hibernate Validator is the one that actually checks
• DTO: Data Transfer Object, a class whose only job is to receive the fields the client sends. It stays separate from the database entity, because the client may touch far fewer fields than the table has
• BindingResult: the "scorecard" object of one validation run — which field failed and what the message says
• @RestControllerAdvice: one global component that catches exceptions thrown by all controllers and turns them into a uniform response
• HTTP status code: the server's one-word verdict on the request — 200 fine, 400 your parameters are wrong, 401 not signed in, 500 I broke

The four boxes above are the four question sets of this article: how to write the rules (Sections 3 and 6), when they trigger (Sections 2, 4 and 5), who catches the exception (Section 8), and what the response looks like (Sections 9 and 14).

After this article you should be able to answer three questions:

• Why does the same "must not be empty" get copied a hundred times inside if statements but only once as @NotBlank?
• My DTO clearly carries @NotBlank, yet an empty string still reached the database. Why? (Nine times out of ten, @Valid is missing.)
• A BizException is thrown deep in a service — what makes it come back as 409 instead of a blank error page, and who caught it on the way?

Start with a block almost everyone has written — the "null-check hell":

This has four problems: validation is tangled with business logic, every endpoint copies it again, the error shape is inconsistent, and a Map loses all typing. After annotation-based refactoring:

The same rules now sit next to the fields — self-explanatory, reusable, and scannable by tooling. Every if is gone from the business method. That is the entire point of a validation framework.

Since Spring Boot 2.3, validation has been split out of spring-boot-starter-web and must be added explicitly:

It pulls in Hibernate Validator, which implements JSR-303 (Bean Validation). The two annotations look alike but play different roles:

One line to remember: use @Valid to validate a whole object, and @Validated when you need groups or to validate loose parameters.

Beyond the two annotations, you need to know which cell of the chain presses the switch. The chain below can be clicked through one stage at a time; stage ④ makes the point: validation is not a check you write in the business code, it is a round the framework runs after argument resolution finishes.

There are twenty-odd constraints, but what beginners actually have to tell apart is what each one really stops. Skip the memorising — play a round instead: the left column is the annotation, the right column is its true reach, and every wrong pick explains itself on the spot.

Loose parameters like @RequestParam and @PathVariable cannot take @Valid directly; you must annotate the class with @Validated:

Here a validation failure throws not MethodArgumentNotValidException but ConstraintViolationException — they are handled differently, so the global handler must cover both, or the error falls through to the 500 fallback.

For the same DTO, id must be empty on create (the database generates it) and non-empty on update. Groups express both rule sets with one DTO:

Remember the last frame of that animation: there are only two ways out — add groups to the constraint, or let your marker interface extends Default. The second one keeps every unlabelled rule working and touches the least code.

When the built-ins cannot express a business rule, write your own. A phone check has two parts: the annotation and the validator.

Each method has a job: initialize reads the annotation attributes, isValid decides, and message/groups/payload are the required members the spec demands (missing them fails startup). A custom validator must be thread-safe — compile the Pattern once and reuse a single instance.

Hard-coded text serves one language only. Pull the messages into resource bundles and multiple languages come for free:

Point at the bundle and its encoding:

With i18n in place, put a placeholder key in the constraint's message rather than literal text, e.g. @NotBlank(message = "{NotBlank}"), and MessageSource resolves it by the request Locale at runtime.

By now every validation failure throws an exception. Without unified handling, Spring returns its default error page or a stack dump — the front end receives a 500 or HTML instead of a structured "which field failed".

@RestControllerAdvice + @ExceptionHandler is the only proper answer. Here is a complete implementation you can copy:

Key points:

• Handler methods match by specificity — the BizException handler is more specific than the Exception fallback, so a business exception is always caught by it first
• Every handler pins the HTTP status with @ResponseStatus or ResponseEntity, instead of always returning 200
• The fallback Exception handler is a net, not a bin: its job is to miss nothing, not to swallow anything — log.error the full stack and return only the traceId to the user

A unified error response carries three things: a machine-readable error code, a human-readable message, and field-level detail. A validation failure looks like this:

That data array did not appear out of thin air: it is frame ④ of the animation, expanded. To see how the scorecard is written page by page and then read back, step through the debugger below — the same MethodArgumentNotValidException, from the throw to the 400, travels exactly one resolver chain:

• @Valid on a primitive parameter does nothing: @Valid @RequestParam String name triggers no validation — @Valid only means "start validating an object / cascade", it cannot add a constraint to a string. For loose parameters, put @Validated on the class and write @NotBlank at the parameter
• Validation exceptions swallowed by the fallback: if you only write @ExceptionHandler(Exception.class), MethodArgumentNotValidException gets taken by it during matching (it is an Exception too), so a validation failure returns 500. Either write a dedicated handler for validation exceptions, or restrict the fallback to truly unexpected errors — the deciding factor is specificity, not the order in the source

Figure 1 gives the whole pipeline view:

Reading ten diagrams is worth less than clicking once. Run these six kernel experiments in order — about 30 seconds each — they cover the six scenes of validation and exceptions.

First, understand how your parameters get into the method at all. @PathVariable, @RequestParam and @RequestBody follow three different resolver paths, and validation runs only after resolution succeeds. Click through all five arguments, and pay special attention to the last one, "no resolver" — that is exactly the error you have seen in your own project:

Next, look at how the response gets written out. A validation failure has to become JSON, a 406 comes from the message converters, and @Validated on the class throws a different exception — all three are decided by this chain:

This is the centrepiece: the exception resolver chain. The five arguments map to five fates — validation 400, conversion failure, caught by your own @ExceptionHandler, swept up by @ControllerAdvice, and the worst one, "nobody handles it → 500". Do run the none case; it prints where the blank error page actually comes from:

Finally zoom out and see which stop validation and exceptions occupy as one request crosses the whole application. Compare valid (validation failed) with db (database down): both fail, one at the entrance and one at the bottom layer — but both leave through the same global advice:

One more trap you only feel once you click it: drop a single @ResponseBody and the string you return is treated as a view name to be resolved against templates, so the browser receives a blank page instead of JSON. Getting the exit's shape wrong is exactly as damaging as getting the status code wrong. Walk all four cases, and missing in particular:

Once those six are done, replay the animation from the opening — now every step should map onto something you just clicked: step 3's ExceptionHandlerExceptionResolver is the err lab, and step 4's "most specific first" is exactly why the Exception.class only cell of the sandbox blows up:

The labs are clicked, now it is your turn at the prompt. This console is a real container and every line of output is computed by the Java kernel in your browser — beans tells you whether your advice was ever installed, lab runs the six scenarios above:

If beans does not list GlobalExceptionHandler, it lives outside the base package of your main class — then no handler runs at all, and that check is worth doing before you audit annotation spellings. Read commands 3 and 4 back to back: that pair is the watershed between 400 and the blank 500 page. The last two show the same return "error" becoming a view name or a JSON body depending on which controller you chose.

"An annotation means validation happens" is the biggest beginner illusion. Drag the three switches below and the real outcome appears instantly — learn the table first, memorise the rules later:

How to read this sandbox: look at the Trigger column first. Whenever it says none, validation never runs regardless of the other two switches. Then check "Constraints sit on", because loose parameters and nested objects are two special branches. Finally look at "Global handler" — it decides whether this failure reaches the client as a clean 400 or as a pile of 500.

What beginners fear most is a log too long to read. Every fragment below can be copied verbatim into a search engine — do not paraphrase it, search engines match fully qualified class names, not your description.

Start with the scorecard you most need to learn to read. When MethodArgumentNotValidException is thrown, everything useful lives in the BindingResult, yet most people only stare at the top of the stack:

Three things to extract: ① for argument [0] means the 0th method parameter failed, not the return value; ② on field 'username' is the real offending field, mapped straight onto your DTO property; ③ rejected value [] shows what was actually received (an empty string here) and default message [...] is the sentence you will send back to the client. The fixed way to read it is e.getBindingResult().getFieldErrors(), and each FieldError gives you getField() / getRejectedValue() / getDefaultMessage().

The stack worth learning to read is this kind: it explodes at startup or on the first request, it is long, and only one line is actually guilty. Click through it and see which frames merely passed by:

That resolver chain from the debugger is the model to keep: the same exception becomes a helpful 400 or a useless 500 purely depending on which exit catches it. That is also why a global advice beats per-method try-catch:

Three failure classes in the table above — the blank page, the bare 500, the missing message — are usually resolved by making the framework show its work first. All of those switches must be off in production, so generate them instead of hand-copying:

Check the result against one rule: include-message / include-stacktrace belong to dev only. In production the only thing the client may learn is the traceId your own advice writes — the framework's words should never be spoken to the front end.

Build an endpoint that really returns field errors, end to end. Step one is the dependency (mandatory since Boot 2.3):

Send one good request and two bad ones:

Expected response (status line and body aligned word for word):

The console should show no ERROR stack trace — a validation failure is an expected 4xx, and logging it as an error drowns the real incidents. If you get an HTML error page instead, ApiErrors was never scanned (its package sits outside the main class's tree).

Goal: three one-line edits, three completely different failure shapes.

1. Delete @Valid from the create parameter, change nothing else, resend the same curl. You will observe HTTP 200, an empty username after ok:, and not even a warning in the log — a silent skip, which is worse than an error.
2. Change the first handler's parameter type in ApiErrors from MethodArgumentNotValidException to Exception, restore @Valid, resend. You will observe the status becoming 500, the body becoming Boot's default {timestamp,status,error,path}, and an ERROR stack appearing in the log — the fallback stole the validation exception.
3. Also delete the class-level @Validated, then request /api/signup/-1. You will observe no ConstraintViolationException at all, just a clean detail:-1 — loose parameters are validated only because of the class-level @Validated; a lone @Positive on the parameter does nothing.

Build an POST /api/orders endpoint that strings every capability of this article together: the body contains a shipping address (nested object) and a list of order lines (collection elements), and create/update share one DTO with different rules.

Acceptance checklist:

• [ ] Validation on the nested AddressDTO and on List<OrderItemDTO> actually fires (send one illegal element and confirm a field name with an index, like items[1].skuId, appears in the response)
• [ ] create uses ValidGroups.Create and update uses ValidGroups.Update, while shared rules such as @NotBlank apply under both groups (via explicit groups or by letting the marker interface extend Default)
• [ ] At least one custom annotation (e.g. @Phone), returning your own message on bad input
• [ ] The global advice covers at least five types: MethodArgumentNotValidException, BindException, ConstraintViolationException, BizException, and the Exception fallback
• [ ] The fallback body carries a traceId, and grepping that same string finds the full stack in the log
• [ ] Curl produces four distinct statuses: 200 / 400 (validation) / 409 or a business code (insufficient stock) / 500 (throw a RuntimeException deliberately)
• [ ] You can explain why validation failures should be logged at warn, not error