gridpilot.gg/apps/website/ERROR_HANDLING_GUIDE.md

GridPilot Error Handling & UX Enhancement Guide

This guide documents the comprehensive error handling system implemented to improve both end-user experience and developer debugging capabilities.

Overview

The enhanced error handling system addresses the "property rememberMe should not exist" validation error and provides a robust framework for handling form validation and API errors with clear user feedback and detailed developer information.

Problem Statement

Original Issue: When users attempted to log in, they encountered a cryptic error message "property rememberMe should not exist" displayed directly next to the form. This was caused by:

1. API Validation: NestJS ValidationPipe with forbidNonWhitelisted: true rejecting unexpected properties
2. Poor UX: Raw validation errors shown to users without context or user-friendly messaging
3. Poor Developer UX: No debugging information or context for troubleshooting

Solution Architecture

1. Enhanced Error Utilities (lib/utils/errorUtils.ts)

Key Functions:

• parseApiError(): Extracts validation errors and user-friendly messages from API responses
• formatValidationErrorsForForm(): Maps API field names to form field names
• logErrorWithContext(): Developer-friendly logging with full context
• createUserErrorSummary(): Creates user-friendly error summaries

Features:

• Automatic detection of validation errors vs general errors
• Support for NestJS validation error format
• Context-aware error classification
• Development-only detailed logging

2. Enhanced Form Hook (lib/hooks/useEnhancedForm.ts)

Key Features:

• Centralized form state management
• Real-time validation with debouncing
• Automatic error mapping from API to form fields
• Developer context logging on errors
• Retry logic for network errors

Usage Example:

const {
  formState,
  setFormState,
  handleChange,
  handleSubmit,
  setFormError,
} = useEnhancedForm<LoginFormValues>({
  initialValues: { email: '', password: '', rememberMe: false },
  validate: validateLoginForm,
  component: 'LoginPage',
  onSubmit: async (values) => {
    await authService.login(values);
  },
  onError: (error, values) => {
    // Custom error handling
  },
  onSuccess: () => {
    // Success logic
  },
});

3. Validation Utilities (lib/utils/validation.ts)

Validation Functions:

• emailValidation(): Email format validation
• passwordValidation(): Password strength requirements
• nameValidation(): Name format and length validation
• confirmPasswordValidation(): Password matching validation
• checkPasswordStrength(): Password strength scoring

Form Validators:

• validateLoginForm(): Login form validation
• validateSignupForm(): Signup form validation

4. Enhanced Error Display Components

EnhancedFormError Component

• User View: Clear, actionable error messages
• Developer View: Toggleable technical details
• Features:
  • Color-coded severity levels
  • Retry buttons for network errors
  • Dismissible errors
  • Collapsible technical details
  • Full error context display

FormErrorSummary Component

• Compact error display for form submissions
• Quick dismiss action
• Consistent styling

5. Updated Login Page (app/auth/login/page.tsx)

Improvements:

• Uses useEnhancedForm hook
• Enhanced error display with EnhancedFormError
• Developer details toggle in development
• Better loading states
• Improved form field binding

Key Benefits

For End Users

1. Clear Error Messages: "Please check your email and password" instead of "property rememberMe should not exist"
2. Actionable Guidance: Specific instructions on how to fix issues
3. Visual Feedback: Color-coded errors and loading states
4. Error Recovery: Retry buttons for network issues
5. Dismissible Errors: Users can clear error messages

For Developers

1. Detailed Context: Full error context including endpoint, status, timestamp
2. Development Tools: Toggleable technical details panel
3. Console Logging: Structured logs with form data and context
4. Error Classification: Network vs validation vs server errors
5. Troubleshooting Hints: Automatic detection of common issues (CORS, etc.)

Error Flow

Login Error Flow

1. User submits form → useEnhancedForm.handleSubmit()
2. Client validation → validateLoginForm()
3. API call → authService.login()
4. Error occurs → parseApiError() extracts details
5. Display error → EnhancedFormError shows user-friendly message
6. Developer logging → logErrorWithContext() with full context
7. User action → Retry or dismiss

Validation Error Flow

1. API returns 400 → Validation pipe rejects rememberMe
2. Error parsing → Detects validation error format
3. Field mapping → Maps rememberMe to form field
4. Form state update → Sets field-specific error
5. User sees → "Invalid input" with field details

Implementation Details

rememberMe Fix

The original issue was that rememberMe was being sent in the login request but the API validation was rejecting it. The fix involved:

1. API DTO: Already had @IsOptional() and @ApiProperty({ required: false })
2. Service: Already handled rememberMe correctly
3. Root Cause: Missing proper error handling and user feedback

Solution: Enhanced error handling system that gracefully handles validation errors and provides clear feedback.

Error Context

Every error includes:

{
  timestamp: string;
  component: string;
  action: string;
  formData?: Record<string, unknown>;
  userId?: string;
  sessionId?: string;
}

Development vs Production

• Development: Full technical details, stack traces, form data
• Production: User-friendly messages only, no sensitive data

Testing Recommendations

1. Validation Errors: Test with invalid emails, weak passwords
2. Network Errors: Test with CORS issues, timeouts
3. API Errors: Test with server errors, rate limiting
4. Edge Cases: Empty forms, special characters, long inputs

Future Enhancements

1. Error Analytics: Track error rates and types
2. Auto-retry: Automatic retry for transient errors
3. Error Recovery: Suggest solutions based on error type
4. Multi-language: Error messages in different languages
5. Accessibility: Screen reader friendly error announcements

Files Created/Modified

New Files

• lib/utils/errorUtils.ts - Error parsing and utilities
• lib/hooks/useEnhancedForm.ts - Enhanced form hook
• lib/utils/validation.ts - Validation rules and functions
• components/errors/EnhancedFormError.tsx - Error display component
• ERROR_HANDLING_GUIDE.md - This documentation

Modified Files

• app/auth/login/page.tsx - Updated with enhanced error handling
• lib/api/base/ApiError.ts - (No changes needed, already robust)
• components/errors/ErrorDisplay.tsx - (Existing, enhanced with new patterns)

Quick Start

To use the enhanced error handling in new forms:

// 1. Import utilities
import { useEnhancedForm } from '@/lib/hooks/useEnhancedForm';
import { validateLoginForm } from '@/lib/utils/validation';
import { EnhancedFormError } from '@/components/errors/EnhancedFormError';

// 2. Create form
const { formState, handleChange, handleSubmit } = useEnhancedForm({
  initialValues: { email: '', password: '' },
  validate: validateLoginForm,
  onSubmit: async (values) => {
    await api.login(values);
  },
});

// 3. Display errors
{formState.submitError && (
  <EnhancedFormError 
    error={new Error(formState.submitError)}
    onDismiss={() => setFormState(prev => ({ ...prev, submitError: undefined }))}
  />
)}

This system provides a foundation for consistent, user-friendly error handling across the entire application.