Error Handling Patterns¶

Error Handling Philosophy¶

• Graceful Degradation: Always provide fallback behavior when errors occur.
• User-Friendly Messages: Never expose technical error details to end users.
• Comprehensive Logging: Log detailed error information for debugging.
• Error Recovery: Provide mechanisms to recover from errors when possible.

Client-Side Error Handling¶

React Error Boundaries¶

• Implement error boundaries for component tree isolation.
• Catch rendering errors and display fallback UI.
• Log errors to error tracking service.
• Provide user-friendly error messages.

Form Error Handling¶

• Validate inputs client-side before submission.
• Display validation errors inline.
• Provide clear error messages.
• Allow users to correct errors easily.

Server-Side Error Handling¶

Server Component Error Handling¶

• Use try-catch blocks for async operations.
• Handle errors gracefully in server components.
• Provide fallback content when data fetch fails.
• Log errors for debugging.

Error Types¶

Authentication Errors¶

• Handle expired tokens gracefully.
• Redirect to login when authentication fails.
• Provide clear messages about authentication issues.
• Preserve intended destination after re-authentication.

Network Errors¶

• Handle offline scenarios.
• Provide retry mechanisms.
• Cache data for offline access.
• Show appropriate offline indicators.

Validation Errors¶

• Validate all user inputs.
• Provide specific error messages for each validation failure.
• Highlight invalid fields.
• Allow easy error correction.

Permission Errors¶

• Handle unauthorized access gracefully.
• Provide clear messages about permission issues.
• Redirect to appropriate pages.
• Log unauthorized access attempts.

Error Logging¶

Client-Side Logging¶

• Log errors to console in development.
• Send errors to error tracking service in production.
• Include context (user ID, page, action).
• Don't log sensitive information.

Server-Side Logging¶

• Log all errors with full context.
• Include stack traces for debugging.
• Log request details (method, URL, headers).
• Use structured logging format.

Observability¶

• Primary service: PostHog (error tracking, product analytics, and log ingestion), wired through the shared @open-learning-hub/observability package. Canonical policy: 092-analytics-observability.mdc.
• Canonical structured logging: 091-structured-logging.mdc. It owns the logger API, emit contract, Edge-safety requirements, redaction rules, parity contract, and logger test expectations. Server logs are additionally forwarded to PostHog via the OpenTelemetry log-sink seam described there.
• Correlation: route handlers, server actions, and server components should attach a traceId to logs and event/exception properties. Include tenantId and userId only when available and authorized for the current request, and never send emails or names.
• Client errors: production client-side error boundaries (error.tsx / global-error.tsx) report to PostHog error tracking with route/boundary and digest, gated on analytics consent. Development keeps console logging for fast local debugging.
• Server errors: log the original error server-side with stack and sanitized context, capture it via the server analytics seam (captureException), then return user-safe messages to the client.
• Monitoring: alert on repeated auth failures, rate-limit spikes, CMS integration failures, payment webhook failures, and unexpected 5xx responses.

Error Messages¶

User-Facing Messages¶

• Use clear, non-technical language.
• Provide actionable guidance.
• Avoid exposing system internals.
• Be helpful and supportive.

Developer Messages¶

• Include technical details in logs.
• Provide stack traces.
• Include request context.
• Make debugging easier.

Error Recovery¶

Retry Mechanisms¶

• Implement retry logic for transient errors.
• Use exponential backoff.
• Limit retry attempts.
• Provide user feedback during retries.

Fallback Behavior¶

• Provide fallback UI when data fails to load.
• Use cached data when available.
• Show partial content when possible.
• Gracefully degrade functionality.

Error Boundaries¶

Usage¶

• Wrap major sections in error boundaries.
• Isolate errors to prevent full app crashes.
• Provide context-specific fallback UI.
• Allow users to continue using unaffected parts.

Best Practices¶

• Always handle errors explicitly.
• Never let errors crash the application.
• Provide user-friendly error messages.
• Log errors comprehensively.
• Test error scenarios.
• Document error handling patterns.