# Mutation Error Handlers Audit

**Date**: 2026-01-11  
**Action**: 3.4.1.2 - Audit all mutation error handlers  
**Status**: ✅ Complete

## Summary

This document lists all mutation error handlers found in the codebase, identifying where mutations occur and how errors are currently handled.

## Mutation Error Handler Patterns

### Pattern 1: State-Managed Mutation Errors
Components that use `useState` to track mutation errors and display them with `ErrorDisplay`:

1. **ProfileForm.tsx** (`apps/web/src/features/user/components/ProfileForm.tsx`)
   - **Mutations**: Profile update
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: 65, 172, 179-184, 224-233

2. **LibraryPage.tsx** (`apps/web/src/features/library/pages/LibraryPage.tsx`)
   - **Mutations**: Add track to playlist, bulk delete tracks
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: 84, 145, 151, 193, 203, 220, 241-246

3. **Cart.tsx** (`apps/web/src/features/marketplace/components/Cart.tsx`)
   - **Mutations**: Checkout
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: 26, 37, 60, 69-78

4. **AccountSettings.tsx** (`apps/web/src/features/settings/components/AccountSettings.tsx`)
   - **Mutations**: Password change, account deletion, data export
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: 35, 61, 65, 73, 96, 120, 123

5. **MarketplaceHome.tsx** (`apps/web/src/pages/marketplace/MarketplaceHome.tsx`)
   - **Mutations**: Product purchase
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: (from previous work)

6. **RolesPage.tsx** (`apps/web/src/features/roles/pages/RolesPage.tsx`)
   - **Mutations**: Role activation/deactivation, role deletion
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: (from previous work)

7. **SettingsPage.tsx** (`apps/web/src/features/settings/pages/SettingsPage.tsx`)
   - **Mutations**: Settings save
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: (from previous work)

8. **ShareDialog.tsx** (`apps/web/src/features/tracks/components/ShareDialog.tsx`)
   - **Mutations**: Create share link
   - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
   - **Line**: (from previous work)

9. **CommentSection.tsx** (`apps/web/src/features/tracks/components/CommentSection.tsx`)
   - **Mutations**: Create comment
   - **Error Handling**: `mutationError` state via React Query `onError`, displayed as `ErrorDisplay` banner
   - **Line**: (from previous work)

10. **SharePlaylistModal.tsx** (`apps/web/src/features/playlists/components/SharePlaylistModal.tsx`)
    - **Mutations**: Create share link
    - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
    - **Line**: (from previous work)

11. **AddCollaboratorModal.tsx** (`apps/web/src/features/playlists/components/AddCollaboratorModal.tsx`)
    - **Mutations**: Add collaborator
    - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
    - **Line**: (from previous work)

12. **ChatSidebar.tsx** (`apps/web/src/features/chat/components/ChatSidebar.tsx`)
    - **Mutations**: Leave room, delete room
    - **Error Handling**: `mutationError` state via React Query `onError`, displayed as `ErrorDisplay` banner
    - **Line**: (from previous work)

13. **CreateRoomDialog.tsx** (`apps/web/src/features/chat/components/CreateRoomDialog.tsx`)
    - **Mutations**: Create room
    - **Error Handling**: `mutationError` state, displayed as `ErrorDisplay` banner
    - **Line**: (from previous work)

### Pattern 2: React Query useMutation with onError

Components using React Query's `useMutation` with `onError` callback:

1. **CommentSection.tsx** - Uses `createCommentMutation` with `onError`
2. **ChatSidebar.tsx** - Uses `leaveRoomMutation` and `deleteRoomMutation` with `onError`

### Pattern 3: Direct API Calls with Try/Catch

Components making direct API calls with try/catch blocks:

1. **ProfileForm.tsx** - Direct `apiClient.put()` call
2. **LibraryPage.tsx** - Direct `apiClient.post()` and `apiClient.delete()` calls
3. **Cart.tsx** - Direct `apiClient.post()` call
4. **AccountSettings.tsx** - Direct `apiClient.post()` and `apiClient.delete()` calls

## Mutation Types by Category

### User Management
- Profile update (ProfileForm)
- Password change (AccountSettings)
- Account deletion (AccountSettings)
- Data export (AccountSettings)

### Library Management
- Add track to playlist (LibraryPage)
- Bulk delete tracks (LibraryPage)

### Marketplace
- Product purchase (MarketplaceHome)
- Checkout (Cart)

### Playlists
- Create share link (SharePlaylistModal)
- Add collaborator (AddCollaboratorModal)

### Tracks
- Create share link (ShareDialog)
- Create comment (CommentSection)

### Chat
- Create room (CreateRoomDialog)
- Leave room (ChatSidebar)
- Delete room (ChatSidebar)

### Roles & Settings
- Role activation/deactivation (RolesPage)
- Role deletion (RolesPage)
- Settings save (SettingsPage)

## Current Error Handling Status

### ✅ Already Using ErrorDisplay
All mutation error handlers identified are already using `ErrorDisplay` component with banner variant for error presentation.

### ⚠️ Missing Retry Functionality
None of the mutation error handlers currently implement retry functionality. Errors are displayed but users cannot retry failed mutations.

## Recommendations

### High Priority
1. **Add Retry Functionality** (Action 3.4.1.3)
   - Implement retry logic for all mutation error handlers
   - Store mutation function and variables for retry
   - Add retry button to ErrorDisplay (already exists, needs integration)

### Medium Priority
2. **Retry Count Limits** (Action 3.4.1.4)
   - Limit retry attempts to prevent infinite loops
   - Show retry count to user
   - Disable retry after max attempts

### Low Priority
3. **Optimistic Updates with Retry**
   - Consider optimistic updates for mutations
   - Rollback on error, retry on failure
   - Better UX for network failures

## Files Requiring Updates

All files listed above in "Pattern 1: State-Managed Mutation Errors" will need:
1. Store mutation function reference
2. Store mutation variables
3. Add `onRetry` handler to ErrorDisplay
4. Implement retry logic with attempt counting

## Next Steps

1. ✅ Complete: Audit all mutation error handlers
2. ⏭️ Next: Implement retry for failed mutations (Action 3.4.1.3)
3. ⏭️ Next: Add retry count limit (Action 3.4.1.4)