Error Handling Improvements - Implementation Plan

Status: In Progress Created: 2026-01-09 Last Updated: 2026-01-09

---

✅ Completed

Phase 1 - Infrastructure

1. Error Handling Infrastructure

   • Created lib/errorIds.ts - Error ID constants for tracking

   • Created lib/errorLogger.ts - Centralized error logging utility

   • Features: Environment-aware logging, Sentry-ready, user-friendly error messages

2. AuthService - sendMagicLink Fixed

   • Now checks if email actually sent before returning success

   • Returns proper error if email fails in production

   • Uses structured error logging with ERROR_IDS

   • Provides user-friendly error messages

Phase 2 - Critical Issues (5/5 complete)

1. AuthService - verifyMagicLink Fixed

   • Now throws specific error types instead of returning null

   • Errors include: EXPIRED_TOKEN, USER_LOOKUP_FAILED, USER_CREATE_FAILED, PROFILE_LOOKUP_FAILED, PROFILE_CREATE_FAILED

   • Each error includes errorId for tracking and user-friendly message

   • Database errors (code !== 'PGRST116') are distinguished from "not found"

   • Uses logError() with appropriate ERROR_IDS

2. AuthService - acceptInvite Fixed

   • Changed return type to Promise<{ success: boolean; error?: string }>

   • Now logs errors with ERROR_IDS.INVITE_NOT_FOUND, INVITE_EXPIRED, INVITE_ACCEPT_FAILED

   • Returns specific error messages for each failure case

   • verifyMagicLink now checks result and logs warning (non-blocking)

3. App.tsx - Seed Functions Fixed

   • Added seedError state and display banner

   • Both seedShepherdRelationships and seedSupplierRelationships return { success: boolean; error?: string }

   • Uses logError() with ERROR_IDS.RELATIONSHIP_SEED_FAILED

   • Shows dismissable warning banner (non-blocking, login still succeeds)

4. App.tsx - Signup Handlers Fixed

   • Added signupError state

   • Replaced all alert() calls with setSignupError()

   • Updated MinimalSignup component to accept error and onClearError props

   • Displays inline error in form UI with red styling

   • Error clears when user starts typing (allows retry)

   • Uses logError() with ERROR_IDS.SIGNUP_FAILED, USER_CREATE_FAILED, PROFILE_CREATE_FAILED

5. App.tsx - handleSearch Fixed

   • Now provides specific error messages based on error type:

     • 429: Rate limiting message

     • 401/403: API configuration error

     • Network errors: Check internet connection

     • Timeout: Request timed out

     • 5xx: Service temporarily unavailable

   • Uses logError() with ERROR_IDS.SEARCH_FAILED

   • Uses getUserFriendlyErrorMessage() for unknown errors

Phase 3 - High Priority Issues (6/6 complete)

1. SupplierTodoList.tsx Fixed

   • Added loadError state and error UI with retry button

   • Added actionError state for action handler failures

   • Replaced all alert() calls with inline error messages on cards

   • All action handlers (acknowledge, accept, decline, complete, unassign) now use logError()

   • Error IDs: REQUESTS_LOAD_FAILED, REQUEST_ACKNOWLEDGE_FAILED, REQUEST_ACCEPT_FAILED, REQUEST_DECLINE_FAILED, REQUEST_COMPLETE_FAILED, REQUEST_UNASSIGN_FAILED

   • RequestCard component now accepts errorMessage and onClearError props

2. PublicRequestFormHandler.tsx Fixed

   • Removed the throw after catching error (was causing uncaught rejection)

   • Added submitError and isSubmitting state

   • Error displays as fixed banner at top (dismissable)

   • Uses logError() with ERROR_IDS.REQUEST_SUBMIT_FAILED

   • Allows retry without page refresh

3. NotificationService.ts - notifyOrganisation Fixed

   • Added try/catch for QueryService.getLastActiveCompanyUser() with logging

   • Added try/catch for company lookup with logging

   • Uses logError() with ERROR_IDS.ORG_ROUTING_FAILED, COMPANY_LOOKUP_FAILED

   • Added logWarning() for no routing target found

   • No longer fails silently on nested calls

4. RelationshipService.ts Fixed

   • loadFromStorage() now returns { success: boolean; warning?: string }

   • Handles corrupted JSON with recovery (clears and warns user)

   • Handles invalid data format (not an array)

   • Skips corrupted individual entries with warning

   • saveToStorage() now returns { success: boolean; error?: string }

   • Detects QuotaExceededError and provides specific message

   • All callers updated to check saveToStorage result

   • Error IDs: RELATIONSHIP_LOAD_FAILED, RELATIONSHIP_PARSE_FAILED, RELATIONSHIP_SAVE_FAILED, STORAGE_QUOTA_WARNING

5. AuthService.ts - Email Methods Fixed

   • sendDailyAccessEmail and sendMagicLinkEmail updated

   • In dev mode: returns true with console.log (allows testing without email config)

   • In prod with no config: logs error with EMAIL_CONFIG_MISSING and returns false

   • On API errors: logs error with EMAIL_API_ERROR including status code

   • Returns false on any failure with proper logging

6. Toast Notification System Created

   • Created lib/toast.ts - Simple toast notification utility

   • Position: fixed at bottom-right

   • Auto-dismiss: after 3 seconds (configurable)

   • Types: success, error, warning, info

   • Features: slide animations, click to dismiss, clear all

   • Usage: toast.error('message'), toast.success('message')

Phase 4 - Final Issues (5/5 complete)

1. ManualRequestForm.tsx Fixed

   • Added submitError state

   • Replaced alert with inline error banner (dismissable)

   • Uses logError() with ERROR_IDS.REQUEST_SUBMIT_FAILED

   • Error clears when user dismisses

2. FleetRequestForm.tsx Fixed

   • Added submitError state

   • Replaced alert with inline error banner (dismissable)

   • Uses logError() with ERROR_IDS.REQUEST_SUBMIT_FAILED

   • Error displayed prominently below header

3. SupplierDirectory.tsx Fixed

   • Added addSupplierError state

   • Replaced alert with inline error in add form

   • Uses logError() with ERROR_IDS.RELATIONSHIP_CREATE_FAILED

   • Error shows in context where it occurred

4. BaseChatInterface.tsx Fixed

   • Added fileUploadError state

   • Replaced 3 alerts (file type, file size, upload failure) with inline error

   • File validation errors clear file input automatically

   • Uses logError() with ERROR_IDS.FILE_UPLOAD_FAILED

   • Error displays above input area with dismiss button

5. RequestSuccessPage.tsx Fixed

   • Replaced alert with toast.success() for clipboard copy

   • Uses toast notification system (lib/toast.ts)

   • Auto-dismisses after 3 seconds, user can click to dismiss

---

📊 Progress Tracking

Total Issues Identified: 18 Critical: 6 (Phase 1-2) High: 6 (Phase 3) Medium/Low: 6 (Phase 4)

Fixed: 18/18 (100%) ✅ In Progress: 0/18 (0%) Remaining: 0/18 (0%)

Phase 2 Summary (Completed 2026-01-09)

• Fixed all 5 CRITICAL priority issues

• AuthService now throws typed errors with errorIds

• App.tsx uses inline error states instead of alerts

• MinimalSignup component supports external error display

• Search provides specific error guidance

Phase 3 Summary (Completed 2026-01-09)

• Fixed all 6 HIGH priority issues

• SupplierTodoList now shows load errors with retry button

• SupplierTodoList action errors display inline on cards (no alerts)

• PublicRequestFormHandler shows submit errors in fixed banner

• NotificationService logs all failures in org routing

• RelationshipService handles corrupted data gracefully

• AuthService email methods properly log all failure modes

• Created reusable Toast notification system

Phase 4 Summary (Completed 2026-01-09)

• Fixed final 5 MEDIUM/LOW priority issues

• ManualRequestForm shows submit errors inline (no alert)

• FleetRequestForm shows submit errors inline (no alert)

• SupplierDirectory shows add supplier errors inline (no alert)

• BaseChatInterface shows file upload errors inline (no 3 alerts)

• RequestSuccessPage uses toast for success notifications

• ALL 18 ISSUES NOW FIXED (100% COMPLETE)

---

🎯 Next Steps

✅ All 18 error handling issues have been fixed!

Recommended follow-ups:

1. Test error paths intentionally in dev/staging

2. Consider adding Sentry integration for production error tracking

3. Monitor error rates after deployment using ERROR_IDS

4. Document error codes for support team reference

5. Optional: Add more toast notifications for success actions

---

📝 Usage Examples

Error Logging

import { logError, logWarning, getUserFriendlyErrorMessage } from '../lib/errorLogger';
import { ERROR_IDS } from '../lib/errorIds';

// Log an error
logError('Failed to load requests', {
  errorId: ERROR_IDS.REQUESTS_LOAD_FAILED,
  userId: currentUserId,
  error: err,
});

// Get user-friendly message
const message = getUserFriendlyErrorMessage(err, 'Unable to load requests.');

Toast Notifications

import { toast } from '../lib/toast';

toast.success('Changes saved!');
toast.error('Failed to submit request');
toast.warning('Please check your input');
toast.info('Processing your request...');

---

📝 Notes

• All fixes use logError() from lib/errorLogger.ts

• All error IDs come from lib/errorIds.ts

• In dev: verbose logging, in prod: user-friendly messages

• Always provide retry mechanisms for recoverable errors

• Never silently continue after critical failures