---
title: Validation Errors
slug: validation-errors
kind: pattern
summary: Tell someone a value is wrong next to that value, at the moment it can be fixed, in words that say what to do — and never take away what they typed.
problem: >-
  A form is submitted and comes back with a red banner at the top, half the
  fields cleared, and a message naming a database constraint. The person now has
  to find which field, work out what was wrong with it, and retype the work the
  page discarded.
family: [capture, edit, recover]
data_shape: [record]
principles: [minimize-distance, orientation, friction]
interaction: [feedback, editing]
density: low
complexity: medium
status: stable
visibility: public
use_when:
  - Any form where a value can be rejected.
  - Rules exist that the person cannot see — uniqueness, formats, limits, relationships.
avoid_when:
  - Never. The only question is whether the rule should exist, not whether to explain it.
alternatives:
  - slug: minimal-form
    when: The real fix is fewer fields, so there is less to get wrong.
  - slug: smart-defaults
    when: The value could be supplied rather than demanded and then rejected.
ask_leo: |
  Fix the validation on this form.

  - Show each error directly beneath the field it belongs to, and mark that
    field. A banner at the top is a summary, never the only message.
  - NEVER clear a field because validation failed. Keep everything the person
    typed, exactly as typed.
  - Validate a field when it loses focus, so problems are found while the person
    is still thinking about that field — not all at once at the end.
  - Once a field has an error, re-check it as they type so the error clears the
    moment it is fixed.
  - Write each message as what happened, why, and what to do. Name the specific
    rule and the specific offending value.
  - Never state a limit only in the error. If there is a maximum, say so before
    they hit it.
  - On submit with several errors, move focus to the first one and, if it is off
    screen, scroll it into view.
  - Do not use colour alone. An error carries a message and a marker as well as
    a red border.
  - Never block submission on a rule the person cannot satisfy from this screen.
    Explain and offer a route instead.
related:
  - title: Words and Labels
    url: /patterns/words-and-labels
    summary: The writing rules that decide whether an error is useful at all.
  - title: Async Actions Need Feedback
    url: /cookbook/async-action-feedback
    summary: The implementation side — never leave a submit in an unknown state.
---

## Anatomy

```
  Purchase order
  ┌────────────────────────────┐
  │ PO-2291                    │  ← what they typed is STILL THERE
  └────────────────────────────┘
  ⚠ PO-2291 is already used by INV-1039.
    Use a different reference, or open INV-1039.
       ↑ what happened · why · what to do — and a route
```

- **Beside the field.** The distance between the message and the thing it is
  about is the cost of fixing it.
- **The value survives.** Clearing a field on error is the single most
  frustrating behaviour in forms, and it is a default in several frameworks.
- **On blur, then live.** Check when they leave the field; once it is wrong,
  re-check as they type so it clears itself.
- **A route out**, when the rule involves something else.

## Why it works

Validation is a conversation about rules the person cannot see. The whole design
question is how quickly and specifically the software explains a rule it knew
all along.

Timing does most of the work. An error found on blur is fixed while the person
is still thinking about that field — the context is loaded, and the correction
costs seconds. The same error surfaced at submit arrives after they have moved
on, and now they must reload the context for every field at once.

Proximity does the rest. A banner saying "3 errors" makes the reader hunt; a
message under the field makes it a correction.

## Getting it wrong

- **Clearing the field.** Unforgivable, and still common — especially with
  passwords and long text.
- **A top banner only**, so the person searches for which of twenty fields is
  wrong.
- **The database's message.** "PG::UniqueViolation" or "constraint violated" is
  not an error message, it is a leak.
- **Errors only on submit**, turning one wrong character into a full-form
  re-read.
- **Limits revealed only by breaking them.** If the maximum is 8 MB, say 8 MB
  before the upload, not after.
- **Colour alone**, so the failed field is invisible to a good number of
  readers.
- **Errors that persist** after the value is corrected, which teaches people to
  ignore them.
- **Blaming the person.** "You entered an invalid value" versus "That reference
  is already in use".

## Exemplars

**Stripe's card fields** validate per field as you leave it, keep everything
typed, and name the specific problem — and the form is short enough that there
is rarely more than one thing wrong at a time, which is itself part of the
design.

**GOV.UK's error summary pattern** is the most rigorously tested version: a
summary at the top whose entries are *links* to the fields, plus the message at
each field. The summary is an addition, never a replacement — worth copying
exactly when a form is long.

The extractable rule: **an error message is an instruction, not a verdict.** If
it does not say what to do next, it has only told the person they are stuck.