Software Practices

Match Failure Output To Surface

OBSERVABILITY-MATCH-FAILURE-OUTPUT-TO-SURFACE

ObservabilityErrorsFailure Output
Give feedback

Summary

Choose a failure-output surface that lets the affected user notice, understand, and act on the failure. Inline errors, alerts, toasts, banners, persistent status, CLI stderr, API responses, and support artifacts have different affordances and failure modes.

Rule

Match failure output to the product surface and consequence.

Why

The same failure can need different presentation on different surfaces. A field validation error is usually more useful near the field. A background sync failure may need a persistent status row. A destructive desktop operation may need an alert, an action, and details. A CLI diagnostic may need stderr and a meaningful exit state, while machine-readable stdout remains stable for scripts. These are product decisions, not universal component rules. If the output is too far from the affected item, too transient, inaccessible, or mixed into the wrong channel, the message can be accurate and still unusable.

Helps

  • Makes user-facing failures discoverable, actionable, accessible, and compatible with automation.

Limits

Do not make every failure modal, persistent, or verbose. Let the product context and consequence set the surface: transient informational events can stay lightweight, while failures that block work, change saved state, require retry, affect support, or become script contracts usually need more durable or structured presentation.

Agent Instruction

Choose the failure surface by consequence and product context. Verify that fixable, durable,
interactive, command-line, API, and support-facing failures expose the needed information where the
affected audience can actually use it.

Mechanisms

Supported by UI component guidelines, accessibility checks, end-to-end tests for visible recovery, CLI stdout/stderr and exit-code tests, API problem-detail schemas, support-report fields, and review that names the surface where the failure appears.

References