Practical guide · AI & interfaces
7 min read
Updated
Form errors: explain, correct, and retry
Build a validation journey with field messages, server errors, focus, and safe recovery.
Direct answer
Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. Link an error summary to the fields, verify keyboard focus, and distinguish server rejection from a network failure. Confirm success only after the server accepts the operation.
01
1. Prepare a small, testable form
Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. A red border alone cannot tell someone what to change.
Prerequisites: an editable form, its business rules, a test environment, and a known server response contract. Use a contact form with name and email as the working example. Write down required fields, accepted formats, and the response that proves persistence; an animation is not that proof.
02
2. Explain the field error
Use a native label and suitable input type, with required or other relevant constraints. Explain format requirements before submission. Validate on submission first; if adding blur validation, avoid interrupting an unfinished value on every keystroke.
For an invalid email, show “Enter an email address such as alex@example.com.” Associate the persistent message with the input using aria-describedby and set aria-invalid="true" only while invalid. Keep useful instructions in that description too. Clear obsolete errors when correction is confirmed; clear setCustomValidity with an empty string when using that API.
03
3. Bring errors into reach
After a rejected submission, show a summary above the form with links to the affected fields. Choose and test one focus strategy: focus that summary (programmatically focusable) for several errors, or the first invalid field for a short form. Do not move focus during ordinary typing.
When errors appear dynamically, make the update perceivable with an appropriate announcement strategy. Test with a screen reader to avoid reading the same error twice through both focus and a live region. The summary links must actually put keyboard users at their fields.
04
4. Handle server rejection and uncertain outcomes
The server must validate independently. Map a field-specific rejection to that field; show a service outage as a form-level message with a retry action. Do not label every field invalid because the network failed. Preserve non-sensitive input and explain any sensitive value that must be entered again.
Prevent concurrent submissions while the request is pending and expose that state in text. For a timeout after sending, check the operation status where supported before retrying: the save may have completed. Agree on duplicate prevention with the backend. Only announce success after the server confirms the intended outcome.
- A field rule fails: explain what value must change beside that field.
- The service is unavailable: keep the form intact and offer a later retry.
- The save outcome is unknown: reconcile its status before repeating the operation.
05
5. Run the recovery scenario
In the test environment, submit an empty form, then a malformed email, then a valid-looking value rejected by the server. Follow summary links using only the keyboard, correct one error, and confirm unrelated input survives. Simulate an outage, restore the service, and complete one successful save.
Record expected and observed behavior, browser, build, and any untested screen-reader combination. A mocked server proves UI handling of the mock; separately verify persistence against the real test backend. This guide supplies a procedure, not a working form endpoint.
Keep this
Evidence to keep
- 01Field error explains a correction and is associated with the field.
- 02Keyboard recovery preserves valid values and reaches confirmed success.
- 03Server rejection, outage, and uncertain save have distinct outcomes.
- 04Each error-summary link moves keyboard focus to its corresponding field.
- 05A corrected field loses its obsolete error without clearing other values.
- 06Pending submission prevents duplicates and exposes a readable status.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- Forms: user notifications (opens in a new tab)W3C WAI · Primary reference supporting the procedure; examples and workflow are original editorial guidance.
- HTML constraint validation (opens in a new tab)MDN · Primary reference supporting the procedure; examples and workflow are original editorial guidance.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “Form errors: explain, correct, and retry” step by step
# Apply the “Form errors: explain, correct, and retry” guide in your agent ## Objective Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. Link an error summary to the fields, verify keyboard focus, and distinguish server rejection from a network failure. Confirm success only after the server accepts the operation. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Build a validation journey with field messages, server errors, focus, and safe recovery. - Preserve the correct decisions already in place. ## Guide steps - 1. 1. Prepare a small, testable form — Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. A red border alone cannot tell someone what to change. - 2. 2. Explain the field error — Use a native label and suitable input type, with required or other relevant constraints. Explain format requirements before submission. Validate on submission first; if adding blur validation, avoid interrupting an unfinished value on every keystroke. - 3. 3. Bring errors into reach — After a rejected submission, show a summary above the form with links to the affected fields. Choose and test one focus strategy: focus that summary (programmatically focusable) for several errors, or the first invalid field for a short form. Do not move focus during ordinary typing. - 4. 4. Handle server rejection and uncertain outcomes — The server must validate independently. Map a field-specific rejection to that field; show a service outage as a form-level message with a retry action. Do not label every field invalid because the network failed. Preserve non-sensitive input and explain any sensitive value that must be entered again. - 5. 5. Run the recovery scenario — In the test environment, submit an empty form, then a malformed email, then a valid-looking value rejected by the server. Follow summary links using only the keyboard, correct one error, and confirm unrelated input survives. Simulate an outage, restore the service, and complete one successful save. ## Acceptance criteria — Evidence to keep - Field error explains a correction and is associated with the field. - Keyboard recovery preserves valid values and reaches confirmed success. - Server rejection, outage, and uncertain save have distinct outcomes. - Each error-summary link moves keyboard focus to its corresponding field. - A corrected field loses its obsolete error without clearing other values. - Pending submission prevents duplicates and exposes a readable status. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:53e95461d63268df6cd4913c95a9bb7c6c5ef187ca26d57c8760267403316e17
Diagnose a problem
Diagnose a “Form errors: explain, correct, and retry” guide gap
# Diagnose a failed application of the “Form errors: explain, correct, and retry” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. 1. Prepare a small, testable form — Connect each rejected value to a useful explanation, preserve valid input, and offer a clear route back to submission. A red border alone cannot tell someone what to change. - 2. 2. Explain the field error — Use a native label and suitable input type, with required or other relevant constraints. Explain format requirements before submission. Validate on submission first; if adding blur validation, avoid interrupting an unfinished value on every keystroke. - 3. 3. Bring errors into reach — After a rejected submission, show a summary above the form with links to the affected fields. Choose and test one focus strategy: focus that summary (programmatically focusable) for several errors, or the first invalid field for a short form. Do not move focus during ordinary typing. - 4. 4. Handle server rejection and uncertain outcomes — The server must validate independently. Map a field-specific rejection to that field; show a service outage as a form-level message with a retry action. Do not label every field invalid because the network failed. Preserve non-sensitive input and explain any sensitive value that must be entered again. - 5. 5. Run the recovery scenario — In the test environment, submit an empty form, then a malformed email, then a valid-looking value rejected by the server. Follow summary links using only the keyboard, correct one error, and confirm unrelated input survives. Simulate an outage, restore the service, and complete one successful save. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Evidence to keep - Field error explains a correction and is associated with the field. - Keyboard recovery preserves valid values and reaches confirmed success. - Server rejection, outage, and uncertain save have distinct outcomes. - Each error-summary link moves keyboard focus to its corresponding field. - A corrected field loses its obsolete error without clearing other values. - Pending submission prevents duplicates and exposes a readable status. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:aa4899e62eb1fa2dda55dc7fd1b4025578fe05e64faeb654b47e5eb898f8bb81
Pack digest: sha256:a9e8735286c8d0159df137878b7c5c6171a35b9366839a3263fad3620d78cdad