Error states during onboarding include clear recovery guidance

Users who hit an error during signup or onboarding abandon at much higher rates than users further along in the lifecycle, because they have not yet invested enough to push through friction. Raw error codes, generic "Something went wrong" toasts, or error messages with no recovery action leave the user guessing whether their email is already registered, whether their password was too short, or whether they should retry — and most will not bother. The user-experience taxon treats error-state clarity as a first-session conversion lever, not a polish item.

Map each known error code to a human-readable message with a specific next action. In src/app/(auth)/signup/page.tsx, maintain an errorMessages record keyed by error code, and render the mapped message inline on the offending field rather than in a generic toast.

const errorMessages: Record<string, string> = {
  'email-exists': 'This email is already registered — try signing in instead.',
  'invalid-password': 'Password must be at least 8 characters.',
  'rate-limited': 'Too many attempts. Please wait a moment.',
};

• ID: saas-onboarding.activation.error-states-clear-recovery

• Severity: high

• What to look for: Count all error handling paths in signup, onboarding, and first-run components: try/catch blocks, error boundary components, form validation display, API error handlers. For each error path, classify whether it renders a human-readable message with a recovery action.

• Pass criteria: All error states display: (1) a human-readable explanation of what went wrong (not a raw error code), (2) a specific action the user can take to recover. Form validation errors are inline. 100% of error paths must have user-friendly messages.

• Fail criteria: Any error state during onboarding displays only: a generic "Something went wrong" message with no guidance; a raw error code or technical error string; an error message with no recovery action offered.

• Skip (N/A) when: No onboarding flow or signup form exists in the codebase.

• Detail on fail: Describe the specific error states that fail. Example: "OAuth error handler displays raw error code from provider. Form submission errors show a generic toast with no field-level detail. Network error shows 'Error: 500' with no retry option."

• Remediation: In your signup form at src/app/(auth)/signup/page.tsx, map error types:

  const errorMessages: Record<string, string> = {
    'email-exists': 'This email is already registered — try signing in instead.',
    'invalid-password': 'Password must be at least 8 characters.',
    'rate-limited': 'Too many attempts. Please wait a moment.',
  };
  

• Cross-reference: For comprehensive error handling patterns across the full application, the SaaS Error Handling Audit covers server-side error management.