member-console/openspec/specs/db-error-presentation/spec.md

db-error-presentation Specification

Purpose

TBD - created by archiving change db-error-translation. Update Purpose after archive.

Requirements

Requirement: Constraint violations render as field-level validation errors

When a database write fails with a constraint violation that web.FieldErrorsFromDB can translate (a constraint named in the handler's ConstraintMessages map, or a violation class with a generic fallback), the handler SHALL render the failure as a validation outcome: HTTP 422 with the page's FieldErrors re-render for form-backed mutations (per operator-ux-conventions §6/§8), or the translated friendly message through the surface's existing banner/toast shape where no FieldErrors machinery exists (member partials, formless actions such as revoke/delete buttons). Handlers SHALL name the constraints their form can plausibly hit in a ConstraintMessages map co-located with the handler, each mapped to the form field to flag and an actionable message.

Scenario: Duplicate workspace slug renders a friendly field message

• WHEN a member submits the workspace create form with a slug that already exists in their organization and the insert fails on the workspaces UNIQUE (org_id, slug) constraint
• THEN the form SHALL re-render with the message "A workspace with this slug already exists in this organization."
• AND the response SHALL NOT contain the constraint name, an SQLSTATE code, or any other driver text

Scenario: Ladder-overlap exclusion renders on the grant form

• WHEN an operator's grant issuance loses a race and the transition fails on the excl_pool_provision_ladders_active_overlap exclusion constraint
• THEN the handler SHALL return 422 and re-render the composite with a field-level message on the issuing form explaining the pool already has an active plan on that ladder

Scenario: Unnamed constraint falls back to a class-level message

• WHEN a write fails on a constraint the handler did not name but whose SQLSTATE class the translator recognizes (unique, foreign-key, check, or value-too-long)
• THEN the handler SHALL render the translator's generic class message through the same validation path, not the raw error

Requirement: Raw database driver text never reaches the UI

Handlers SHALL NOT render the raw text of a database error (err.Error()) — including SQLSTATE codes, constraint or relation names, and driver prefixes — in any response body, banner, toast, or http.Error output. When web.FieldErrorsFromDB cannot translate a write failure (ok == false), the handler SHALL log the full error via slog and render a generic failure message that directs the operator to the server logs.

Scenario: Untranslatable write failure is logged and rendered generically

• WHEN a mutation fails with an error that is not a recognizable constraint violation (for example a lost connection or unexpected schema drift)
• THEN the handler SHALL record the underlying error with slog.Error
• AND the rendered response SHALL contain only a generic failure message (e.g. "Failed to update the product. Details are in the server logs.") with no fragment of the driver error text

Scenario: Error toasts carry no driver text

• WHEN a formless operator action (such as revoking a grant) fails on a translatable constraint
• THEN the error toast and banner SHALL carry the translated friendly message and SHALL NOT include SQLSTATE codes or constraint names

Requirement: Lint enforces the no-raw-error contract

The member-console lint run SHALL include a rule (raw-error-render) that flags any line in a non-test Go file under internal/server where an error's raw text (err.Error() on any identifier ending in err/Err) is concatenated into or passed as an argument to a UI sink — a render* helper, fireErrorToast, fireSuccessToast, or http.Error. Lines that reference slog. SHALL be exempt, since logging the raw error is the required behaviour.

Scenario: Leaky render line is flagged

• WHEN lint scans a handler containing h.renderFooPage(w, r, "", "Failed to save: "+err.Error())
• THEN the run SHALL report a raw-error-render violation with that file and line

Scenario: Structured logging is exempt

• WHEN lint scans a line such as h.Logger.Error("failed to save", slog.Any("error", err))
• THEN the run SHALL NOT report a violation for that line