--- name: error-handling description: "WHAT: Error boundaries with fallback UI and OpenTelemetry span recording. WHEN: isolating component errors, handling GraphQL failures, implementing retry logic. KEYWORDS: ErrorBoundary, error handling, fallback UI, OpenTelemetry, recordException, retry, GraphQL, errorPolicy, scope." --- # Error Handling & Recovery Patterns ## Documentation This skill has comprehensive documentation: - **[Production Examples](.\/references\/examples.md)** - Real-world code examples from the codebase - **[API Reference](.\/references\/api-docs.md)** - Complete API documentation with official links - **[Implementation Patterns](.\/references\/patterns.md)** - Best practices and anti-patterns ## Core Principles **Use ErrorBoundary components to isolate errors and prevent app crashes.** Integrate OpenTelemetry spans to track errors in distributed tracing and provide user-friendly fallback UI with recovery actions. **Why**: Proper error handling prevents entire app crashes, improves user experience with actionable error messages, and enables debugging production issues through distributed tracing. ## When to Use This Skill Use these patterns when: - Wrapping feature components to isolate errors - Integrating error tracking with OpenTelemetry - Creating fallback UI for error states - Handling GraphQL query\/mutation errors - Implementing retry logic for transient failures - Testing error boundaries and error handling paths - Tracking errors in production with distributed tracing ## ErrorBoundary Component ### Component-Level Boundaries Wrap features with ErrorBoundary to isolate errors and prevent app-wide crashes: ```typescript import { ErrorBoundary } from '@libs\/error-boundary'; export const RecipeListScreen = () => { return ( ( )} > <\/ErrorBoundary> ); }; ``` **Key patterns:** - `scope.moduleName`: Identifies where error occurred (required) - `scope.attributes`: Additional context for debugging (optional) - `fallback`: Custom error UI with retry functionality - Automatic OpenTelemetry span creation with `recordException()` **Why**: Component-level boundaries prevent one failing component from crashing the entire app. Errors are isolated, logged to OpenTelemetry, and users see helpful recovery UI. **Production Example**: `git-resources\/shared-mobile-modules\/src\/modules\/comms\/screens\/inbox\/InboxScreen.tsx:1` ### Screen-Level Boundaries Wrap entire app or navigation stacks with top-level ErrorBoundary: ```typescript import { ErrorBoundary } from '@libs\/error-boundary'; export const ScreenEntryProvider: React.FC = ({ children }) => { return ( {children} <\/ErrorBoundary> <\/ZestProvider> <\/AppWithTranslation> <\/SafeAreaProvider> <\/ApolloProvider> <\/QueryClientProvider> ); }; ``` **Why**: Top-level boundaries catch errors that escape component boundaries, ensuring the app never shows a blank white screen. **Production Example**: `git-resources\/shared-mobile-modules\/src\/entry-providers\/providers.tsx:140` ### Error Scope Configuration Always provide scope information for debugging: ```typescript { \/\/ Optional: Custom error handling logError(error, { moduleName: 'Checkout', componentStack }); }} > <\/ErrorBoundary> ``` **Key patterns:** - `moduleName`: Required identifier (e.g., 'Checkout', 'RecipeList') - `attributes`: OpenTelemetry attributes for filtering\/grouping errors - `onError`: Optional callback for custom error handling **Why**: Rich scope data helps identify error sources in production logs and enables filtering errors by team, feature, or screen. **Production Example**: `git-resources\/shared-mobile-modules\/src\/libs\/error-boundary\/ErrorBoundary.tsx:76` ## OpenTelemetry Integration ### Span Recording with Exceptions Always use try-catch-finally pattern with spans: ```typescript import { useTracer } from '@libs\/observability'; import { SpanStatusCode } from '@opentelemetry\/api'; export const useCheckoutFlow = () => { const { startSpan } = useTracer(); const processPayment = async (paymentData: PaymentData) => { const span = startSpan('checkout.processPayment', { attributes: { 'payment.method': paymentData.method, 'cart.total': paymentData.total, 'payment.currency': paymentData.currency, }, }); try { const result = await paymentService.process(paymentData); span.setStatus({ code: SpanStatusCode.OK }); span.setAttributes({ 'payment.transaction_id': result.transactionId, 'payment.status': 'success', }); return result; } catch (error) { span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message, }); span.recordException(error as Error); span.setAttributes({ 'payment.status': 'failed', 'error.type': (error as Error).name, }); throw error; \/\/ Re-throw for caller to handle } finally { span.end(); \/\/ ALWAYS end span } }; return { processPayment }; }; ``` **Key patterns:** - `startSpan()` with descriptive name (`checkout.processPayment`) - `setStatus()` with OK or ERROR - `recordException()` for detailed error tracking - `span.end()` in finally block (CRITICAL) - Attributes for request context and results **Why**: Distributed tracing enables debugging complex async flows in production. Always ending spans in finally blocks prevents memory leaks. **Production Example**: `git-resources\/shared-mobile-modules\/src\/libs\/networking-client\/client\/useFetch.ts:89` ### Automatic GraphQL Tracing GraphQL operations automatically create spans via tracingLink: ```typescript \/\/ Automatic instrumentation in Apollo Client setup import { tracingLink } from '@libs\/graphql\/links\/tracing'; const apolloClient = new ApolloClient({ link: ApolloLink.from([ tracingLink, \/\/ Automatically creates spans for all GraphQL operations httpLink, ]), cache: inMemoryCache, }); ``` **How tracingLink works:** - Creates span for each GraphQL operation: `QUERY GetRecipes`, `MUTATION CreateOrder` - Adds operation type, name, variables (sanitized) - Records GraphQL errors with `recordException()` - Sets span attributes: response status, error count, error messages - Automatically ends span on completion **Why**: Consistent telemetry for all GraphQL operations without manual instrumentation. Errors are automatically tracked in OpenTelemetry. **Production Example**: `git-resources\/shared-mobile-modules\/src\/libs\/graphql\/links\/tracing.ts:115` ## Fallback UI Patterns ### User-Friendly Error Messages Provide clear, actionable error messages based on error type: ```typescript export const ErrorFallback = ({ error, onRetry }: ErrorFallbackProps) => { const styles = useZestStyles(stylesConfig); \/\/ Network errors if (error.networkError || error.message.includes('Network request failed')) { return ( No Internet Connection<\/Text> Please check your connection and try again.<\/Text>