UX Patterns Guide
UI + UX Feedback, Status, And System State standard

Error state

Keep the failure visible near the affected content or task, explain it in user terms, preserve user context, and offer a recovery path such as retry, edit, fallback, cached data, or support escalation.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A system or task failure blocks expected content or action.
  • Recovery, fallback, correction, or escalation is possible.
  • The failure affects a specific page, section, item, form, or workflow state users need to trust.

Avoid when

  • Nothing exists yet and the state is expected.
  • The absence is caused by user search criteria.
  • The system is still loading and has not resolved success, empty, or failure.
  • The issue is a field-level validation error that should be handled inline and in an error summary.
  • The message is non-blocking and can safely be shown as a notification.

Problem it prevents

Users expected content, saving, sync, or progress, but the system failed and they need to understand what failed, what remains safe, and how to recover.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Error state in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

Data may fail to load, save, validate, sync, authorize, or compute.

Pattern promise

Keep the failure visible near the affected content or task, explain it in user terms, preserve user context, and offer a recovery path such as retry, edit, fallback, cached data, or support escalation.

Required state

Normal expected state before failure.

Recovery path

Transient critical errors.

Access contract

Use appropriate alert or status semantics for newly appearing critical errors.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • Reports could not load appears in the report section with the saved filter, Retry, Use cached data, and Contact support actions.
  • A failed save state keeps the draft visible and labels the support reference separately from the user-facing explanation.
  • User input and filter context are preserved after failure, and retry returns to recovered content or a clear still-failed state.
  • Support escalation includes a reference ID while keeping the user's draft intact.
Weak implementation

Vague, hidden, hard to recover from

  • Tiny transient toast for a blocking failure.
  • Technical stack trace or vague Something went wrong message as the main UI.
  • Clearing work after save failure.
  • Letting users keep interacting with stale content without warning.
UI guidance
  • Render a persistent error region near the affected content with a specific failure heading, plain-language cause, preserved context, and recovery actions.
  • Pair visual emphasis with text and iconography, keep diagnostic detail secondary, and distinguish retrying, recovered, cached, and escalated states.
UX guidance
  • Help users recover when expected loading, saving, validation, sync, permission, or computation fails without losing their work.
  • Match the next action to the failure cause: retry transient failures, edit correctable input, use cached fallback for read-only continuity, or provide support reference when recovery is outside the UI.
Implementation contract

What the implementation must handle

States

  • Normal expected state before failure.
  • Pending or retrying state after recovery action starts.
  • Failed state with affected content, cause, and recovery action.
  • Recovered state after retry or fallback succeeds.

Interaction

  • The error remains visible until resolved, intentionally dismissed, replaced by recovered content, or escalated.
  • Recovery controls communicate what they will attempt before activation.
  • User-entered data, filters, scroll context, and unsaved work are preserved where possible.
  • Retry shows an in-progress state and then either recovered content or a still-failed message.

Accessibility

  • Use appropriate alert or status semantics for newly appearing critical errors.
  • Do not rely on color alone to indicate failure.
  • Keep the error heading, explanation, and recovery actions in logical reading order.
  • Associate field-level failures with affected controls when the error is form-specific.

Review

  • Can the user tell exactly what failed and what remains safe?
  • Does the recovery action match the failure cause instead of offering a generic retry for everything?
  • Will user work, filters, or draft content survive the failure and recovery attempt?
Evidence trail

Source-backed claims behind this guidance

Carbon Design System Notification

IBM Carbon Design System - checked

Carbon documents inline, actionable, toast, and modal notification treatment, including when messages need actions or more detail.

VA.gov Error and Alert Messages

VA.gov Design System - checked

VA documents clear, direct error messages with calls to action that tell people what to do next.

Full agent/debug reference

Problem Context

  • Data may fail to load, save, validate, sync, authorize, or compute.
  • Users need confidence that the system did not silently lose their work or show stale data as current.
  • The product can identify enough of the failure cause to choose a specific recovery path.

Selection Rules

  • Choose error state when expected content or task progress is blocked by system, network, permission, validation, save, sync, or computation failure.
  • Keep the affected object, form, query, or section context visible whenever it helps users recover.
  • Offer recovery that matches the failure cause: retry for transient failures, edit for user-correctable data, cached view for read-only fallback, or support escalation for unrecoverable failures.
  • Preserve user-entered data and current criteria unless the recovery action explicitly resets them.
  • Use persistent inline or section-level presentation for blocking failures; reserve transient toasts for non-blocking status.
  • Expose technical identifiers only as support details, not as the main explanation.

Required States

  • Normal expected state before failure.
  • Pending or retrying state after recovery action starts.
  • Failed state with affected content, cause, and recovery action.
  • Recovered state after retry or fallback succeeds.
  • Escalated state with support reference or next contact path.
  • Preserved-draft or preserved-query state after save/load failure.

Interaction Contract

  • The error remains visible until resolved, intentionally dismissed, replaced by recovered content, or escalated.
  • Recovery controls communicate what they will attempt before activation.
  • User-entered data, filters, scroll context, and unsaved work are preserved where possible.
  • Retry shows an in-progress state and then either recovered content or a still-failed message.
  • Support escalation includes enough reference detail to help without dumping stack traces into the primary UI.
  • Users are not allowed to trust stale or partial content unless it is clearly labeled as cached or partial.

Implementation Checklist

  • Describe the failed action, object, or content area in the heading.
  • Write the cause and next step in user terms before exposing technical detail.
  • Provide retry, edit, cached data, offline, or support action according to the failure cause.
  • Preserve user input, query, filters, and drafts after failed save or load.
  • Render blocking failures persistently near the affected content or in a page-level error region.
  • Use alert or status semantics for newly appearing critical errors.
  • Keep diagnostic IDs collapsible or secondary for support use.

Common Generated-UI Mistakes

  • Using a transient toast for critical errors.
  • Showing generic copy such as Something went wrong without recovery.
  • Clearing user input after a failed save.
  • Replacing failed expected content with an empty state.
  • Letting users keep interacting with stale content without warning.
  • Showing raw stack traces or service names as the main message.

Critique Questions

  • Can the user tell exactly what failed and what remains safe?
  • Does the recovery action match the failure cause instead of offering a generic retry for everything?
  • Will user work, filters, or draft content survive the failure and recovery attempt?
Accessibility
  • Use appropriate alert or status semantics for newly appearing critical errors.
  • Do not rely on color alone to indicate failure.
  • Keep the error heading, explanation, and recovery actions in logical reading order.
  • Associate field-level failures with affected controls when the error is form-specific.
  • Avoid moving focus away from the failed section unless doing so helps recovery.
Keyboard Behavior
  • Retry, fallback, edit, and support actions are reachable by keyboard.
  • Focus management should not hide the failed field, draft, or section.
  • After retry succeeds, focus should move to recovered content or a clear success status.
  • After retry fails again, focus should remain near the persistent error and recovery controls.
Variants
  • Inline section error
  • Full-page error
  • Retryable card error
  • Failed save state
  • Cached fallback error
  • Permission failure
  • Offline error

Verification

Source trail checked:

Saved items