veza/apps/web/docs/ERROR_DISPLAY_PATTERNS_AUDIT.md

# Error Display Patterns Audit

**Date**: 2025-01-27  
**Action**: 3.1.1.4 - Audit all error display patterns  
**Status**: ✅ Complete

## Overview

This document catalogs all error display patterns found in the codebase, including toast notifications, inline error displays, error components, and error boundaries.

## Summary Statistics

- **Toast.error() calls**: 35+ instances across 20+ files
- **Inline error divs**: 10+ instances
- **Dedicated error components**: 3 (AuthErrorMessage, PlayerError, ErrorDisplay)
- **Error boundaries**: 2 (ErrorBoundary, PlaylistErrorBoundary)
- **Form validation errors**: 15+ instances (inline text-red-500)

## 1. Toast Error Notifications

### API Client Errors (Global)
**File**: `apps/web/src/services/api/client.ts`
- **Line 857**: `toast.error(apiError.message, {...})` - Global API error handler
- **Line 1026**: `toast.error(enhancedMessage, {...})` - Enhanced error messages
- **Context**: Centralized error handling in API client
- **Recommendation**: Consider ErrorDisplay banner for critical API errors

### Feature-Specific Toast Errors

#### Library/Playlist Features
**File**: `apps/web/src/features/library/pages/LibraryPage.tsx`
- **Line 201**: `toast.error('Impossible de supprimer les pistes')` - Bulk delete error
- **Status**: ✅ Already replaced with ErrorDisplay (Action 3.1.1.3)

**File**: `apps/web/src/features/playlists/components/SharePlaylistModal.tsx`
- **Line 45**: `toast.error(apiError.message)` - Share playlist error
- **Line 59**: `toast.error('Failed to copy link')` - Copy link error
- **Recommendation**: Replace with ErrorDisplay inline variant

**File**: `apps/web/src/features/playlists/components/AddCollaboratorModal.tsx`
- **Line 35**: `toast.error('Username is required')` - Validation error
- **Line 56**: `toast.error(apiError.message)` - Add collaborator error
- **Recommendation**: Replace validation with inline ErrorDisplay, API error with banner

#### Track Features
**File**: `apps/web/src/features/tracks/pages/TrackDetailPage.tsx`
- **Line 63**: `toast.error(errorMessage)` - Track detail error
- **Recommendation**: Replace with ErrorDisplay card variant

**File**: `apps/web/src/features/tracks/components/ShareDialog.tsx`
- **Line 49**: `toast.error(apiError.message)` - Share track error
- **Line 66**: `toast.error('Failed to copy link')` - Copy link error
- **Recommendation**: Replace with ErrorDisplay inline variant

**File**: `apps/web/src/features/tracks/components/CommentSection.tsx`
- **Line 46**: `toast.error(error.message || 'Erreur lors de la publication')` - Comment error
- **Recommendation**: Replace with ErrorDisplay inline variant

#### Chat Features
**File**: `apps/web/src/features/chat/components/ChatSidebar.tsx`
- **Line 48**: `toast.error(error.response?.data?.error || 'Failed to leave room')` - Leave room error
- **Line 63**: `toast.error(error.response?.data?.error || 'Failed to delete room')` - Delete room error
- **Recommendation**: Replace with ErrorDisplay banner variant

**File**: `apps/web/src/features/chat/components/CreateRoomDialog.tsx`
- **Line 28**: `toast.error('Room name is required')` - Validation error
- **Line 56**: `toast.error(apiError.message)` - Create room error
- **Recommendation**: Replace validation with inline ErrorDisplay, API error with banner

#### User/Profile Features
**File**: `apps/web/src/features/user/components/ProfileForm.tsx`
- **Line 170**: `toast.error(apiError.message || t('profile.error') || 'Failed to update profile')` - Profile update error
- **Recommendation**: Replace with ErrorDisplay banner variant

#### Settings Features
**File**: `apps/web/src/features/settings/components/AccountSettings.tsx`
- **Line 61**: `toast.error(apiError.message)` - Account update error
- **Line 69**: `toast.error('Please type DELETE to confirm')` - Validation error
- **Line 89**: `toast.error(apiError.message)` - Password change error
- **Line 115**: `toast.error(apiError.message)` - Account deletion error
- **Recommendation**: Replace validation with inline ErrorDisplay, API errors with banner

**File**: `apps/web/src/features/settings/pages/SettingsPage.tsx`
- **Line 39**: `toast.error(errorMessage)` - Settings load error
- **Line 59**: `toast.error(\`Erreur de validation: ${errors}\`)` - Validation error
- **Line 70**: `toast.error(errorMessage)` - Settings save error
- **Recommendation**: Replace with ErrorDisplay banner variant

#### Marketplace Features
**File**: `apps/web/src/pages/marketplace/MarketplaceHome.tsx`
- **Line 77**: `toast.error(errorMessage)` - Marketplace load error
- **Line 107**: `toast.error(errorMessage)` - Marketplace filter error
- **Recommendation**: Replace with ErrorDisplay card variant

**File**: `apps/web/src/features/marketplace/components/Cart.tsx`
- **Line 34**: `toast.error('Please log in to checkout')` - Auth error
- **Line 39**: `toast.error('Cart is empty')` - Validation error
- **Line 55**: `toast.error(apiError.message)` - Checkout error
- **Recommendation**: Replace auth/validation with inline ErrorDisplay, checkout error with banner

#### Roles Features
**File**: `apps/web/src/features/roles/pages/RolesPage.tsx`
- **Line 45**: `toast.error(errorMessage)` - Roles load error
- **Line 65**: `toast.error(errorMessage)` - Role update error
- **Line 71**: `toast.error('Cannot delete system roles')` - Validation error
- **Line 82**: `toast.error(errorMessage)` - Role delete error
- **Recommendation**: Replace validation with inline ErrorDisplay, API errors with banner

## 2. Inline Error Displays

### Query Error Displays
**File**: `apps/web/src/features/library/pages/LibraryPage.tsx`
- **Lines 402-414**: Query error display with Card component
- **Status**: ✅ Already replaced with ErrorDisplay (Action 3.1.1.3)

**File**: `apps/web/src/features/playlists/components/AddTrackToPlaylistModal.tsx`
- **Line 199**: `error ? (<div>...</div>)` - Inline error display
- **Recommendation**: Replace with ErrorDisplay inline variant

### Profile Error Display
**File**: `apps/web/src/features/profile/pages/UserProfilePage.tsx`
- **Line 90**: `<h2 className="text-2xl font-bold text-destructive mb-2">Error</h2>` - Error heading
- **Recommendation**: Replace with ErrorDisplay card variant

### Upload Error Display
**File**: `apps/web/src/features/upload/components/UploadModal.tsx`
- **Line 330**: `<p className="font-medium">{error}</p>` - Upload error display
- **Recommendation**: Replace with ErrorDisplay inline variant

## 3. Dedicated Error Components

### AuthErrorMessage Component
**File**: `apps/web/src/features/auth/components/AuthErrorMessage.tsx`
- **Purpose**: Displays authentication errors
- **Pattern**: Inline div with red styling
- **Usage**: Used in LoginForm, RegisterForm
- **Recommendation**: Replace with ErrorDisplay inline variant (Action 3.1.1.8)

### PlayerError Component
**File**: `apps/web/src/features/player/components/PlayerError.tsx`
- **Purpose**: Displays audio player errors
- **Pattern**: Custom error component with retry button
- **Features**: Error type detection, retry functionality, dev details
- **Recommendation**: Replace with ErrorDisplay card variant (Action 3.1.1.9)

### ErrorDisplay Component
**File**: `apps/web/src/components/ui/ErrorDisplay.tsx`
- **Status**: ✅ Newly implemented (Action 3.1.1.2)
- **Purpose**: Standardized error display component
- **Usage**: Currently used in LibraryPage

## 4. Error Boundaries

### ErrorBoundary Component
**File**: `apps/web/src/components/ErrorBoundary.tsx`
- **Usage**: Wraps routes in `router/index.tsx` (40+ instances)
- **Usage**: Wraps app in `app/App.tsx`
- **Pattern**: React error boundary with fallback UI
- **Recommendation**: Update fallback UI to use ErrorDisplay component

### PlaylistErrorBoundary Component
**File**: `apps/web/src/features/playlists/components/PlaylistErrorBoundary.tsx`
- **Usage**: Wraps playlist components
- **Pattern**: Specialized error boundary for playlists
- **Recommendation**: Update fallback UI to use ErrorDisplay component (Action 3.1.1.10)

## 5. Form Validation Errors

### Inline Form Errors
**File**: `apps/web/src/features/user/components/ProfileForm.tsx`
- **Lines 287, 302, 317, 332, 350, 369, 397**: `<p className="text-sm text-red-500">{errors.field.message}</p>`
- **Pattern**: Inline validation error messages
- **Recommendation**: Keep as-is (form validation errors are appropriate inline)

**File**: `apps/web/src/features/upload/components/UploadModal.tsx`
- **Line 381**: `<p className="text-sm text-destructive">{errors.title.message}</p>`
- **Pattern**: Inline validation error
- **Recommendation**: Keep as-is (form validation)

### FormField Component
**File**: `apps/web/src/components/ui/FormField.tsx`
- **Line 124**: `<p className="text-xs text-red-500 dark:text-red-400">{error}</p>`
- **Pattern**: Standardized form field error display
- **Recommendation**: Keep as-is (form validation errors are appropriate inline)

### AuthFormField Component
**File**: `apps/web/src/features/auth/components/AuthFormField.tsx`
- **Pattern**: Auth-specific form field with error display
- **Recommendation**: Keep as-is (form validation errors are appropriate inline)

## 6. API Client Error Handling

**File**: `apps/web/src/services/api/client.ts`
- **Lines 857, 1026**: Global toast.error calls for API errors
- **Pattern**: Centralized error notification
- **Recommendation**: Consider ErrorDisplay banner for critical errors, keep toast for transient errors

## 7. Utility Functions

### apiToastHelper
**File**: `apps/web/src/utils/apiToastHelper.ts`
- **Line 53**: `toast.error(message, { duration })` - Helper function
- **Usage**: Used for consistent toast error styling
- **Recommendation**: Keep utility, but consider ErrorDisplay integration

## Categorization by Error Type

### 1. Query Errors (Data Fetching)
- **Pattern**: `isError` from React Query
- **Current Display**: Inline divs, toast notifications
- **Recommendation**: ErrorDisplay card/inline variant with retry
- **Files**: LibraryPage, TrackDetailPage, MarketplaceHome, RolesPage, SettingsPage

### 2. Mutation Errors (Data Updates)
- **Pattern**: `catch` blocks in async functions
- **Current Display**: Toast notifications
- **Recommendation**: ErrorDisplay banner variant (dismissible)
- **Files**: All feature files with mutations

### 3. Validation Errors (Form Input)
- **Pattern**: React Hook Form errors
- **Current Display**: Inline text-red-500
- **Recommendation**: Keep as-is (appropriate for form validation)

### 4. Network Errors (API Failures)
- **Pattern**: Axios errors, network failures
- **Current Display**: Toast notifications, API client errors
- **Recommendation**: ErrorDisplay banner variant with retry
- **Files**: API client, feature files

### 5. Runtime Errors (Component Failures)
- **Pattern**: Error boundaries
- **Current Display**: ErrorBoundary fallback UI
- **Recommendation**: Update ErrorBoundary to use ErrorDisplay
- **Files**: ErrorBoundary, PlaylistErrorBoundary

### 6. Player Errors (Audio Playback)
- **Pattern**: PlayerError component
- **Current Display**: Custom PlayerError component
- **Recommendation**: Replace with ErrorDisplay card variant
- **Files**: PlayerError.tsx

## Priority Classification

### HIGH Priority (Critical User-Facing Errors)
1. Query errors (data fetching failures)
2. Network errors (API failures)
3. Runtime errors (component crashes)

### MEDIUM Priority (User Action Errors)
1. Mutation errors (data update failures)
2. Auth errors (login/register failures)
3. Player errors (audio playback failures)

### LOW Priority (Transient/Validation Errors)
1. Form validation errors (keep as-is)
2. Copy link errors (toast is appropriate)
3. Validation messages (keep as-is)

## Recommendations Summary

1. **Replace toast.error() for query errors** → ErrorDisplay card/inline variant
2. **Replace toast.error() for mutation errors** → ErrorDisplay banner variant
3. **Keep toast.error() for transient actions** → Copy link, quick actions
4. **Keep inline validation errors** → Form field errors are appropriate
5. **Update ErrorBoundary fallback** → Use ErrorDisplay component
6. **Replace PlayerError** → Use ErrorDisplay card variant
7. **Replace AuthErrorMessage** → Use ErrorDisplay inline variant

## Next Steps

1. ✅ Action 3.1.1.4: Audit complete
2. ⏭️ Action 3.1.1.5: Create error display strategy document
3. ⏭️ Action 3.1.1.6: Replace toast.error() calls based on strategy
4. ⏭️ Action 3.1.1.7: Remove duplicate error displays
5. ⏭️ Action 3.1.1.8: Update AuthErrorMessage component
6. ⏭️ Action 3.1.1.9: Update PlayerError component
7. ⏭️ Action 3.1.1.10: Update ErrorBoundary fallback UI