@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/modules/02-core-guides-mapping-08-error-handling.md

@@ -1,1142 +1,1142 @@
-# UniversalMapper Error Handling
-
-[← Back to Mapping Guide](../mapping-readme.md)
-
-**Module 8** | **Level**: Intermediate | **Time**: 25 minutes
-
----
-
-## Overview
-
-Understanding error handling is critical for building robust integrations. The UniversalMapper provides comprehensive error handling with clear error messages and fail-fast behavior for required fields.
-
-**Key Concepts:**
-- ✅ **Individual record error handling** - Each record processed independently
-- ✅ **Fail-fast for required fields** - Prevents partial/corrupt data
-- ✅ **Error aggregation** - Collects all errors for arrays
-- ✅ **Rich error context** - Field name, source path, input value, timestamps
-
----
-
-## Table of Contents
-
-1. [Error Types Overview](#error-types-overview)
-2. [Fatal vs Non-Fatal Errors](#fatal-vs-non-fatal-errors)
-3. [Array Error Handling](#array-error-handling)
-4. [Error Result Structure](#error-result-structure)
-5. [Common Error Scenarios](#common-error-scenarios)
-6. [Production Patterns](#production-patterns)
-7. [Troubleshooting Guide](#troubleshooting-guide)
-
----
-
-## Error Types Overview
-
-The UniversalMapper produces two main types of errors:
-
-| Error Type | When Thrown | Result | Retryable |
-|------------|-------------|--------|-----------|
-| **Required Field Error** | Required field missing/null/empty | `success: false`, record skipped | ❌ No - Fix data or config |
-| **Resolver Error** | Resolver execution fails | `success: false` (required) or warning (optional) | ❌ No - Fix resolver or data |
-| **Resolver Not Found** | Referenced resolver doesn't exist | `success: false`, record skipped | ❌ No - Fix config |
-| **Configuration Error** | Invalid mapping config | Throws exception | ❌ No - Fix config |
-
----
-
-## Fatal vs Non-Fatal Errors
-
-### ❌ Fatal Errors (Stops Record Processing)
-
-**Result:** `{ success: false, data: null, errors: [...] }`
-
-The mapper **immediately stops** processing and returns failure for:
-
-#### 1. Required Field Missing
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'product.sku', required: true },
-    quantity: { source: 'product.qty', required: true }
-  }
-});
-
-const result = await mapper.map({ product: { sku: 'ABC' } }); // Missing qty
-
-// Result:
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'quantity': Required field 'quantity' is missing or empty (source: product.qty)"
-  ]
-}
-```
-
-**Error includes:**
-- Field name: `quantity`
-- Source path: `product.qty`
-- Clear reason: "missing or empty"
-
-#### 2. Required Field is Null/Empty
-
-```typescript
-const result = await mapper.map({
-  product: {
-    sku: '',        // ❌ Empty string
-    qty: null       // ❌ Null
-  }
-});
-
-// Both fail validation
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: product.sku)"
-  ]
-}
-```
-
-**Validation checks:**
-- `value === null` ❌ Fails
-- `value === undefined` ❌ Fails
-- `value === ''` ❌ Fails (empty string)
-- `value === 0` ✅ Passes (valid number)
-- `value === false` ✅ Passes (valid boolean)
-
-#### 3. Required Field Resolver Fails
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt',
-      required: true
-    }
-  }
-});
-
-const result = await mapper.map({ qty: 'ABC' }); // Not a number
-
-// Result:
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'ABC' as integer"
-  ]
-}
-```
-
-**Error includes:**
-- Resolver name: `sdk.parseInt`
-- Input value: `ABC`
-- Original error: "Cannot parse 'ABC' as integer"
-
-#### 4. Nested Required Field Fails
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    customer: {
-      fields: {
-        email: { source: 'email', required: true },
-        firstName: { source: 'firstName', required: true }
-      }
-    }
-  }
-});
-
-const result = await mapper.map({
-  customer: { firstName: 'John' } // Missing email
-});
-
-// Result:
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'email': Required field 'email' is missing or empty"
-  ]
-}
-```
-
-**Nested errors propagate up** - Parent field also fails if any child required field fails.
-
-#### 5. Resolver Not Found
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    status: {
-      value: 'ACTIVE',
-      resolver: 'sdk.unknownResolver' // ❌ Doesn't exist
-    }
-  }
-});
-
-const result = await mapper.map({});
-
-// Result:
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'status': Resolver 'sdk.unknownResolver' not found"
-  ]
-}
-```
-
-**Common cause:** Typo in resolver name or forgot to register custom resolver.
-
----
-
-### ⚠️ Non-Fatal Errors (Processing Continues)
-
-**Result:** `{ success: true, data: {...}, errors: [...] }`
-
-The mapper **continues processing** but collects warnings for:
-
-#### 1. Optional Field Missing (Skipped)
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'sku', required: true },
-    description: { source: 'description' } // Optional, no defaultValue
-  }
-});
-
-const result = await mapper.map({ sku: 'ABC' }); // No description
-
-// Result:
-{
-  success: true,  // ✅ Succeeds because required field present
-  data: { sku: 'ABC' },  // description not included (undefined fields are skipped)
-  errors: undefined,
-  skippedFields: ['description']  // Field names that were skipped
-}
-```
-
-**Important:** Undefined optional fields are **automatically skipped** from the output (correct JSON behavior). Field names are tracked in `skippedFields` for reference.
-
-**To always include a field:** Add `defaultValue` to the field configuration:
-```typescript
-{
-  description: { 
-    source: 'description', 
-    defaultValue: ''  // Empty string if missing
-  }
-}
-```
-
-#### 2. Optional Field Uses Default Value
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'sku', required: true },
-    status: { source: 'status', defaultValue: 'ACTIVE' }
-  }
-});
-
-const result = await mapper.map({ sku: 'ABC' }); // No status
-
-// Result:
-{
-  success: true,
-  data: {
-    sku: 'ABC',
-    status: 'ACTIVE'  // ✅ Default value used
-  },
-  errors: undefined
-}
-```
-
-#### 3. Optional Field Resolver Fails
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'sku', required: true },
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt' // Optional field, resolver fails
-    }
-  }
-});
-
-const result = await mapper.map({ sku: 'ABC', qty: 'invalid' });
-
-// Result:
-{
-  success: true,  // ✅ Required field succeeded
-  data: { sku: 'ABC' },
-  errors: [
-    "Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'invalid' as integer"
-  ]
-}
-```
-
-**Note:** Error is logged but doesn't stop processing since field is optional.
-
----
-
-## Array Error Handling
-
-The UniversalMapper has **built-in array error handling** that processes each item individually and aggregates results.
-
-### Automatic Array Processing
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'sku', required: true },
-    quantity: { source: 'qty', resolver: 'sdk.parseInt', required: true }
-  }
-});
-
-// Pass array directly to mapper
-const records = [
-  { sku: 'ABC', qty: '10' },    // ✅ Valid
-  { sku: 'DEF' },               // ❌ Missing qty
-  { sku: 'GHI', qty: '20' },    // ✅ Valid
-  { qty: '30' }                 // ❌ Missing sku
-];
-
-const result = await mapper.map(records);
-
-// Result:
-{
-  success: true,  // ✅ At least one item succeeded
-  data: [
-    { sku: 'ABC', quantity: 10 },
-    { sku: 'GHI', quantity: 20 }
-  ],
-  errors: [
-    "Failed to map field 'quantity': Required field 'quantity' is missing or empty (source: qty)",
-    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: sku)"
-  ]
-}
-```
-
-**Behavior:**
-- ✅ Successful items collected in `data` array
-- ❌ Failed items logged in `errors` array
-- Result is `success: true` if **at least one item** succeeds
-- Result is `success: false` if **all items** fail
-
-### Processing Individual Records
-
-```typescript
-// Production pattern: Process records one-by-one for detailed error tracking
-const mappedRecords = [];
-const failedRecords = [];
-
-for (let i = 0; i < records.length; i++) {
-  const record = records[i];
-  const recordId = record.sku || record.id || `index-${i}`;
-
-  const mappingResult = await mapper.map(record);
-
-  if (mappingResult.success) {
-    mappedRecords.push(mappingResult.data);
-    log.info(`✅ Record ${recordId} mapped successfully`);
-  } else {
-    failedRecords.push({
-      recordId,
-      index: i,
-      record,
-      errors: mappingResult.errors
-    });
-    log.error(`❌ Record ${recordId} mapping failed`, {
-      errors: mappingResult.errors,
-      record: JSON.stringify(record)
-    });
-  }
-}
-
-log.info('Mapping complete', {
-  total: records.length,
-  successful: mappedRecords.length,
-  failed: failedRecords.length,
-  successRate: `${((mappedRecords.length / records.length) * 100).toFixed(2)}%`
-});
-```
-
-### Nested Array Error Handling
-
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    orderId: { source: 'id', required: true },
-    items: {
-      source: 'items',
-      isArray: true,
-      fields: {
-        sku: { source: 'sku', required: true },
-        quantity: { source: 'qty', required: true }
-      }
-    }
-  }
-});
-
-const result = await mapper.map({
-  id: 'ORDER-123',
-  items: [
-    { sku: 'ABC', qty: 10 },  // ✅ Valid
-    { qty: 5 }                // ❌ Missing sku
-  ]
-});
-
-// Result:
-{
-  success: false,  // ❌ Required nested field failed
-  data: null,
-  errors: [
-    "Failed to map field 'items': Required field 'sku' is missing or empty"
-  ]
-}
-```
-
-**Nested array errors propagate up** - Parent field fails if any array item has required field errors.
-
----
-
-## Error Result Structure
-
-Every mapping operation returns a `MappingResult`:
-
-```typescript
-interface MappingResult {
-  /** Whether mapping succeeded */
-  success: boolean;
-
-  /** Mapped data (null if failed) */
-  data: any;
-
-  /** Errors encountered during mapping */
-  errors?: string[];
-
-  /** Fields that were skipped because they were undefined (field names only) */
-  skippedFields?: string[];
-}
-```
-
-### Success Cases
-
-#### 1. Complete Success
-
-```typescript
-{
-  success: true,
-  data: { sku: 'ABC', quantity: 10 },
-  errors: undefined  // No errors
-}
-```
-
-#### 2. Success with Skipped Fields
-
-```typescript
-{
-  success: true,
-  data: { sku: 'ABC' },  // description field skipped (was undefined)
-  errors: undefined,
-  skippedFields: ['description']  // Field names that were skipped
-}
-```
-
-#### 3. Success with Resolver Errors (Optional Fields)
-
-```typescript
-{
-  success: true,
-  data: { sku: 'ABC' },
-  errors: [
-    "Failed to map field 'description': Resolver 'sdk.uppercase' failed: Cannot uppercase null"
-  ]
-}
-```
-
-### Failure Cases
-
-#### 1. Required Field Missing
-
-```typescript
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: product.sku)"
-  ]
-}
-```
-
-#### 2. Multiple Errors (Array Processing)
-
-```typescript
-{
-  success: true,  // Some items succeeded
-  data: [
-    { sku: 'ABC', quantity: 10 },
-    { sku: 'DEF', quantity: 20 }
-  ],
-  errors: [
-    "Failed to map field 'sku': Required field 'sku' is missing or empty",
-    "Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'XYZ' as integer"
-  ]
-}
-```
-
----
-
-## Common Error Scenarios
-
-### Scenario 1: Required Field Missing
-
-**Problem:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'product.sku', required: true }
-  }
-});
-
-const result = await mapper.map({ product: {} });
-```
-
-**Error:**
-```
-Failed to map field 'sku': Required field 'sku' is missing or empty (source: product.sku)
-```
-
-**Solutions:**
-
-✅ **Option 1: Fix source data**
-```typescript
-await mapper.map({ product: { sku: 'ABC123' } });
-```
-
-✅ **Option 2: Make field optional with default**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: {
-      source: 'product.sku',
-      defaultValue: 'UNKNOWN'  // No longer required
-    }
-  }
-});
-```
-
-✅ **Option 3: Use resolver to generate value**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    sku: {
-      resolver: 'sdk.uuid',  // Generates UUID if source missing
-      required: true
-    }
-  }
-});
-```
-
----
-
-### Scenario 2: Resolver Fails on Invalid Data
-
-**Problem:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt',
-      required: true
-    }
-  }
-});
-
-const result = await mapper.map({ qty: 'ABC' });
-```
-
-**Error:**
-```
-Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'ABC' as integer
-```
-
-**Solutions:**
-
-✅ **Option 1: Fix source data**
-```typescript
-await mapper.map({ qty: '123' }); // Valid number string
-```
-
-✅ **Option 2: Use parseInt with optional field and default**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt',  // Already safe, returns 0 for invalid input
-      required: false,            // Make optional to allow default
-      defaultValue: 0             // Fallback for missing/invalid
-    }
-  }
-});
-```
-
-✅ **Option 3: Validate before mapping**
-```typescript
-const sourceData = { qty: 'ABC' };
-
-// Pre-validation
-if (!/^\d+$/.test(sourceData.qty)) {
-  throw new Error(`Invalid quantity: ${sourceData.qty}`);
-}
-
-await mapper.map(sourceData);
-```
-
----
-
-### Scenario 3: Resolver Not Found
-
-**Problem:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    status: {
-      value: 'active',
-      resolver: 'sdk.uppercas'  // ❌ Typo: should be 'sdk.uppercase'
-    }
-  }
-});
-```
-
-**Error:**
-```
-Failed to map field 'status': Resolver 'sdk.uppercas' not found
-```
-
-**Solutions:**
-
-✅ **Option 1: Fix typo**
-```typescript
-resolver: 'sdk.uppercase'  // ✅ Correct spelling
-```
-
-✅ **Option 2: Check available resolvers**
-```typescript
-console.log(mapper.getResolverNames());
-// ['sdk.uppercase', 'sdk.lowercase', 'sdk.parseInt', ...]
-```
-
-✅ **Option 3: Register custom resolver if needed**
-```typescript
-mapper.registerResolver('custom.uppercas', (value) => {
-  return String(value).toUpperCase();
-});
-```
-
----
-
-### Scenario 4: Contradictory Configuration
-
-**Problem:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    status: {
-      source: 'status',
-      required: true,
-      defaultValue: 'ACTIVE'  // ❌ Contradictory: required + defaultValue
-    }
-  }
-});
-```
-
-**Warning (logged to console):**
-```
-⚠️  Field 'status' has both required=true and defaultValue.
-This is contradictory - the defaultValue will never be used because required validation
-fails before defaultValue is applied. Consider using required=false if you want a fallback value.
-```
-
-**Solution:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    status: {
-      source: 'status',
-      required: false,        // ✅ Allow missing with default
-      defaultValue: 'ACTIVE'
-    }
-  }
-});
-```
-
----
-
-### Scenario 5: Nested Required Field Missing
-
-**Problem:**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    customer: {
-      fields: {
-        email: { source: 'email', required: true },
-        phone: { source: 'phone', required: true }
-      }
-    }
-  }
-});
-
-const result = await mapper.map({
-  customer: { email: 'test@example.com' } // Missing phone
-});
-```
-
-**Error:**
-```
-Failed to map field 'phone': Required field 'phone' is missing or empty
-```
-
-**Solutions:**
-
-✅ **Option 1: Provide required field**
-```typescript
-await mapper.map({
-  customer: {
-    email: 'test@example.com',
-    phone: '555-1234'  // ✅ Provided
-  }
-});
-```
-
-✅ **Option 2: Make field optional**
-```typescript
-const mapper = new UniversalMapper({
-  fields: {
-    customer: {
-      fields: {
-        email: { source: 'email', required: true },
-        phone: { source: 'phone', required: false }  // ✅ Optional
-      }
-    }
-  }
-});
-```
-
----
-
-## Production Patterns
-
-### Pattern 1: Individual Record Error Tracking
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-interface RecordError {
-  recordId: string;
-  index: number;
-  error: string[];
-  record: any;
-  timestamp: string;
-}
-
-async function processRecords(
-  records: any[],
-  mapper: UniversalMapper,
-  log: any
-): Promise<{
-  successful: any[];
-  failed: RecordError[];
-  summary: string;
-}> {
-  const successful = [];
-  const failed: RecordError[] = [];
-
-  for (let i = 0; i < records.length; i++) {
-    const record = records[i];
-    const recordId = record.id || record.sku || `index-${i}`;
-
-    try {
-      const mappingResult = await mapper.map(record);
-
-      if (mappingResult.success) {
-        successful.push(mappingResult.data);
-        log.info(`✅ Record ${recordId} processed`, { index: i });
-      } else {
-        failed.push({
-          recordId,
-          index: i,
-          error: mappingResult.errors || ['Unknown error'],
-          record,
-          timestamp: new Date().toISOString()
-        });
-        log.error(`❌ Record ${recordId} failed`, {
-          index: i,
-          errors: mappingResult.errors
-        });
-      }
-    } catch (error: any) {
-      // Unexpected error (config issue, etc.)
-      failed.push({
-        recordId,
-        index: i,
-        error: [error.message],
-        record,
-        timestamp: new Date().toISOString()
-      });
-      log.error(`💥 Record ${recordId} threw exception`, {
-        error: error.message,
-        stack: error.stack
-      });
-    }
-  }
-
-  return {
-    successful,
-    failed,
-    summary: `Processed ${records.length} records: ${successful.length} succeeded, ${failed.length} failed`
-  };
-}
-```
-
-### Pattern 2: Error Categorization
-
-```typescript
-enum ErrorCategory {
-  VALIDATION = 'validation',
-  MAPPING = 'mapping',
-  RESOLVER = 'resolver',
-  UNKNOWN = 'unknown'
-}
-
-interface CategorizedError {
-  category: ErrorCategory;
-  recordId: string;
-  message: string;
-  record: any;
-}
-
-function categorizeError(error: string, record: any, recordId: string): CategorizedError {
-  if (error.includes('Required field')) {
-    return {
-      category: ErrorCategory.VALIDATION,
-      recordId,
-      message: error,
-      record
-    };
-  } else if (error.includes('Resolver')) {
-    return {
-      category: ErrorCategory.RESOLVER,
-      recordId,
-      message: error,
-      record
-    };
-  } else if (error.includes('Failed to map')) {
-    return {
-      category: ErrorCategory.MAPPING,
-      recordId,
-      message: error,
-      record
-    };
-  } else {
-    return {
-      category: ErrorCategory.UNKNOWN,
-      recordId,
-      message: error,
-      record
-    };
-  }
-}
-
-async function processWithCategorization(
-  records: any[],
-  mapper: UniversalMapper,
-  log: any
-) {
-  const results = {
-    successful: [],
-    errors: {
-      [ErrorCategory.VALIDATION]: [] as CategorizedError[],
-      [ErrorCategory.MAPPING]: [] as CategorizedError[],
-      [ErrorCategory.RESOLVER]: [] as CategorizedError[],
-      [ErrorCategory.UNKNOWN]: [] as CategorizedError[]
-    }
-  };
-
-  for (let i = 0; i < records.length; i++) {
-    const record = records[i];
-    const recordId = record.id || `index-${i}`;
-
-    const mappingResult = await mapper.map(record);
-
-    if (mappingResult.success) {
-      results.successful.push(mappingResult.data);
-    } else {
-      // Categorize each error
-      (mappingResult.errors || []).forEach(errorMsg => {
-        const categorized = categorizeError(errorMsg, record, recordId);
-        results.errors[categorized.category].push(categorized);
-      });
-    }
-  }
-
-  // Log summary by category
-  log.info('Processing complete', {
-    successful: results.successful.length,
-    validationErrors: results.errors[ErrorCategory.VALIDATION].length,
-    mappingErrors: results.errors[ErrorCategory.MAPPING].length,
-    resolverErrors: results.errors[ErrorCategory.RESOLVER].length,
-    unknownErrors: results.errors[ErrorCategory.UNKNOWN].length
-  });
-
-  return results;
-}
-```
-
-### Pattern 3: Using PartialBatchRecovery for Retries
-
-```typescript
-import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
-
-async function processWithRecovery(
-  records: any[],
-  mapper: UniversalMapper,
-  client: FluentClient,
-  jobId: string,
-  log: any
-) {
-  const recovery = new PartialBatchRecovery(log);
-
-  const result = await recovery.processBatchWithRecovery(
-    records,
-    async (batch) => {
-      // Map records
-      const mapped = [];
-      for (const rec of batch) {
-        const mappingResult = await mapper.map(rec);
-        if (mappingResult.success) {
-          mapped.push(mappingResult.data);
-        } else {
-          throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
-        }
-      }
-
-      // Send to Fluent
-      return client.sendBatch(jobId, mapped);
-    },
-    {
-      maxRetries: 3,
-      retryOnlyFailed: true,
-      checkpointKey: `job-${jobId}`,
-      retryDelayMs: 1000
-    }
-  );
-
-  log.info('Batch processing complete', {
-    total: result.totalRecords,
-    successful: result.successCount,
-    failed: result.failedCount,
-    failedRecords: result.failedRecords
-  });
-
-  return result;
-}
-```
-
----
-
-## Troubleshooting Guide
-
-### Quick Diagnostic Checklist
-
-When you encounter mapping errors, check:
-
-1. **✅ Is the field required?**
-   - Check `required: true` in field config
-   - Required fields must have non-null/non-empty values
-
-2. **✅ Is the source path correct?**
-   - Verify path matches actual data structure
-   - Check for typos in field names
-   - Use `console.log(JSON.stringify(sourceData))` to inspect
-
-3. **✅ Is the resolver name correct?**
-   - Check spelling: `sdk.parseInt` not `sdk.parseInt`
-   - Verify with `mapper.getResolverNames()`
-   - Ensure custom resolvers are registered
-
-4. **✅ Is the data type compatible with resolver?**
-   - `sdk.parseInt` expects string/number (returns 0 for invalid, already safe)
-   - `sdk.parseFloat` expects string/number (returns 0 for invalid, already safe)
-   - `sdk.uppercase` expects string
-   - Make fields optional with `defaultValue` for fallback behavior
-
-5. **✅ Are there nested required fields?**
-   - Check all nested field configs
-   - Nested required fields propagate errors up
-
-### Common Error Messages
-
-| Error Message | Cause | Solution |
-|---------------|-------|----------|
-| `Required field 'X' is missing or empty` | Field is null/undefined/'' | Provide value or make optional |
-| `Resolver 'X' not found` | Typo or unregistered resolver | Fix spelling or register resolver |
-| `Resolver 'X' failed: ...` | Resolver threw during execution | Fix input data or use safe resolver |
-| `Failed to map field 'X': ...` | Generic mapping failure | Check field config and data |
-
-### Debug Logging
-
-```typescript
-const mockLogger = {
-  info: (...args: any[]) => console.log('[INFO]', ...args),
-  debug: (...args: any[]) => console.log('[DEBUG]', ...args),
-  warn: (...args: any[]) => console.warn('[WARN]', ...args),
-  error: (...args: any[]) => console.error('[ERROR]', ...args)
-};
-
-const mapper = new UniversalMapper(config, { logger: mockLogger });
-
-// Now see detailed logs during mapping
-const result = await mapper.map(data);
-```
-
----
-
-## Best Practices
-
-### ✅ DO:
-
-1. **Always check `mappingResult.success`**
-   ```typescript
-   if (mappingResult.success) {
-     await client.sendBatch(jobId, mappingResult.data);
-   } else {
-     log.error('Mapping failed', mappingResult.errors);
-   }
-   ```
-
-2. **Log detailed error context**
-   ```typescript
-   log.error('Record mapping failed', {
-     recordId,
-     errors: mappingResult.errors,
-     record: JSON.stringify(record)
-   });
-   ```
-
-3. **Use optional fields with defaults for non-critical data**
-   ```typescript
-   description: { source: 'desc', defaultValue: '' }
-   ```
-
-4. **Process records individually for better error tracking**
-   ```typescript
-   for (const record of records) {
-     const result = await mapper.map(record);
-     // Handle individually
-   }
-   ```
-
-5. **Categorize errors for monitoring**
-   ```typescript
-   if (error.includes('Resolver')) {
-     metrics.incrementResolverErrors();
-   }
-   ```
-
-### ❌ DON'T:
-
-1. **Don't ignore `mappingResult.errors`**
-   ```typescript
-   // ❌ BAD
-   const result = await mapper.map(data);
-   await client.sendBatch(jobId, result.data); // Might be null!
-
-   // ✅ GOOD
-   if (result.success) {
-     await client.sendBatch(jobId, result.data);
-   }
-   ```
-
-2. **Don't use required + defaultValue together**
-   ```typescript
-   // ❌ BAD - defaultValue never used
-   { source: 'field', required: true, defaultValue: 'X' }
-
-   // ✅ GOOD - Optional with default
-   { source: 'field', required: false, defaultValue: 'X' }
-   ```
-
-3. **Don't catch and ignore errors silently**
-   ```typescript
-   // ❌ BAD
-   try {
-     await mapper.map(record);
-   } catch (error) {
-     // Silently ignored
-   }
-
-   // ✅ GOOD
-   try {
-     const result = await mapper.map(record);
-     if (!result.success) {
-       log.error('Mapping failed', result.errors);
-     }
-   } catch (error) {
-     log.error('Unexpected error', error);
-   }
-   ```
-
-4. **Don't assume all array items succeed**
-   ```typescript
-   // ❌ BAD
-   const result = await mapper.map(records);
-   console.log(`Processed ${records.length} records`);
-
-   // ✅ GOOD
-   const result = await mapper.map(records);
-   console.log(`Processed ${result.data.length}/${records.length} records`);
-   if (result.errors) {
-     console.log(`Errors: ${result.errors.length}`);
-   }
-   ```
-
----
-
-## Related Documentation
-
-- [Mapping Foundations](./mapping-01-foundations.md) - Core mapping concepts
-- [Custom Resolvers](../resolvers/mapping-resolvers-resolver-guide.md) - Building custom resolvers
-- [Error Handling Pattern Guide](../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - General error handling
-- [GraphQL Mutation Mapper Error Handling](../graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md) - GraphQL-specific errors
-
----
-
-## Summary
-
-**Key Takeaways:**
-
-1. ✅ **UniversalMapper provides built-in error handling** - No need to wrap each record in try-catch
-2. ✅ **Required fields fail-fast** - Prevents partial/corrupt data
-3. ✅ **Optional fields continue with warnings** - Flexible error handling
-4. ✅ **Array processing is automatic** - Each item processed individually
-5. ✅ **Rich error context** - Field name, source path, resolver name, input value
-6. ✅ **MappingResult tells you everything** - `success`, `data`, `errors`
-
-**Next Steps:**
-
-- Try the [Error Scenarios Test Suite](../../../../tests/unit/services/mapping/universal-mapper.test.ts)
-- Review [Production Templates](../../../01-TEMPLATES/) for real-world examples
-- Check [Resolver Troubleshooting](../resolvers/mapping-resolvers-resolver-troubleshooting.md) for resolver-specific issues
-
----
-
-[← Back to Mapping Guide](../mapping-readme.md)
+# UniversalMapper Error Handling
+
+[← Back to Mapping Guide](../mapping-readme.md)
+
+**Module 8** | **Level**: Intermediate | **Time**: 25 minutes
+
+---
+
+## Overview
+
+Understanding error handling is critical for building robust integrations. The UniversalMapper provides comprehensive error handling with clear error messages and fail-fast behavior for required fields.
+
+**Key Concepts:**
+- ✅ **Individual record error handling** - Each record processed independently
+- ✅ **Fail-fast for required fields** - Prevents partial/corrupt data
+- ✅ **Error aggregation** - Collects all errors for arrays
+- ✅ **Rich error context** - Field name, source path, input value, timestamps
+
+---
+
+## Table of Contents
+
+1. [Error Types Overview](#error-types-overview)
+2. [Fatal vs Non-Fatal Errors](#fatal-vs-non-fatal-errors)
+3. [Array Error Handling](#array-error-handling)
+4. [Error Result Structure](#error-result-structure)
+5. [Common Error Scenarios](#common-error-scenarios)
+6. [Production Patterns](#production-patterns)
+7. [Troubleshooting Guide](#troubleshooting-guide)
+
+---
+
+## Error Types Overview
+
+The UniversalMapper produces two main types of errors:
+
+| Error Type | When Thrown | Result | Retryable |
+|------------|-------------|--------|-----------|
+| **Required Field Error** | Required field missing/null/empty | `success: false`, record skipped | ❌ No - Fix data or config |
+| **Resolver Error** | Resolver execution fails | `success: false` (required) or warning (optional) | ❌ No - Fix resolver or data |
+| **Resolver Not Found** | Referenced resolver doesn't exist | `success: false`, record skipped | ❌ No - Fix config |
+| **Configuration Error** | Invalid mapping config | Throws exception | ❌ No - Fix config |
+
+---
+
+## Fatal vs Non-Fatal Errors
+
+### ❌ Fatal Errors (Stops Record Processing)
+
+**Result:** `{ success: false, data: null, errors: [...] }`
+
+The mapper **immediately stops** processing and returns failure for:
+
+#### 1. Required Field Missing
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'product.sku', required: true },
+    quantity: { source: 'product.qty', required: true }
+  }
+});
+
+const result = await mapper.map({ product: { sku: 'ABC' } }); // Missing qty
+
+// Result:
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'quantity': Required field 'quantity' is missing or empty (source: product.qty)"
+  ]
+}
+```
+
+**Error includes:**
+- Field name: `quantity`
+- Source path: `product.qty`
+- Clear reason: "missing or empty"
+
+#### 2. Required Field is Null/Empty
+
+```typescript
+const result = await mapper.map({
+  product: {
+    sku: '',        // ❌ Empty string
+    qty: null       // ❌ Null
+  }
+});
+
+// Both fail validation
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: product.sku)"
+  ]
+}
+```
+
+**Validation checks:**
+- `value === null` ❌ Fails
+- `value === undefined` ❌ Fails
+- `value === ''` ❌ Fails (empty string)
+- `value === 0` ✅ Passes (valid number)
+- `value === false` ✅ Passes (valid boolean)
+
+#### 3. Required Field Resolver Fails
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt',
+      required: true
+    }
+  }
+});
+
+const result = await mapper.map({ qty: 'ABC' }); // Not a number
+
+// Result:
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'ABC' as integer"
+  ]
+}
+```
+
+**Error includes:**
+- Resolver name: `sdk.parseInt`
+- Input value: `ABC`
+- Original error: "Cannot parse 'ABC' as integer"
+
+#### 4. Nested Required Field Fails
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    customer: {
+      fields: {
+        email: { source: 'email', required: true },
+        firstName: { source: 'firstName', required: true }
+      }
+    }
+  }
+});
+
+const result = await mapper.map({
+  customer: { firstName: 'John' } // Missing email
+});
+
+// Result:
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'email': Required field 'email' is missing or empty"
+  ]
+}
+```
+
+**Nested errors propagate up** - Parent field also fails if any child required field fails.
+
+#### 5. Resolver Not Found
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    status: {
+      value: 'ACTIVE',
+      resolver: 'sdk.unknownResolver' // ❌ Doesn't exist
+    }
+  }
+});
+
+const result = await mapper.map({});
+
+// Result:
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'status': Resolver 'sdk.unknownResolver' not found"
+  ]
+}
+```
+
+**Common cause:** Typo in resolver name or forgot to register custom resolver.
+
+---
+
+### ⚠️ Non-Fatal Errors (Processing Continues)
+
+**Result:** `{ success: true, data: {...}, errors: [...] }`
+
+The mapper **continues processing** but collects warnings for:
+
+#### 1. Optional Field Missing (Skipped)
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'sku', required: true },
+    description: { source: 'description' } // Optional, no defaultValue
+  }
+});
+
+const result = await mapper.map({ sku: 'ABC' }); // No description
+
+// Result:
+{
+  success: true,  // ✅ Succeeds because required field present
+  data: { sku: 'ABC' },  // description not included (undefined fields are skipped)
+  errors: undefined,
+  skippedFields: ['description']  // Field names that were skipped
+}
+```
+
+**Important:** Undefined optional fields are **automatically skipped** from the output (correct JSON behavior). Field names are tracked in `skippedFields` for reference.
+
+**To always include a field:** Add `defaultValue` to the field configuration:
+```typescript
+{
+  description: { 
+    source: 'description', 
+    defaultValue: ''  // Empty string if missing
+  }
+}
+```
+
+#### 2. Optional Field Uses Default Value
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'sku', required: true },
+    status: { source: 'status', defaultValue: 'ACTIVE' }
+  }
+});
+
+const result = await mapper.map({ sku: 'ABC' }); // No status
+
+// Result:
+{
+  success: true,
+  data: {
+    sku: 'ABC',
+    status: 'ACTIVE'  // ✅ Default value used
+  },
+  errors: undefined
+}
+```
+
+#### 3. Optional Field Resolver Fails
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'sku', required: true },
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt' // Optional field, resolver fails
+    }
+  }
+});
+
+const result = await mapper.map({ sku: 'ABC', qty: 'invalid' });
+
+// Result:
+{
+  success: true,  // ✅ Required field succeeded
+  data: { sku: 'ABC' },
+  errors: [
+    "Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'invalid' as integer"
+  ]
+}
+```
+
+**Note:** Error is logged but doesn't stop processing since field is optional.
+
+---
+
+## Array Error Handling
+
+The UniversalMapper has **built-in array error handling** that processes each item individually and aggregates results.
+
+### Automatic Array Processing
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'sku', required: true },
+    quantity: { source: 'qty', resolver: 'sdk.parseInt', required: true }
+  }
+});
+
+// Pass array directly to mapper
+const records = [
+  { sku: 'ABC', qty: '10' },    // ✅ Valid
+  { sku: 'DEF' },               // ❌ Missing qty
+  { sku: 'GHI', qty: '20' },    // ✅ Valid
+  { qty: '30' }                 // ❌ Missing sku
+];
+
+const result = await mapper.map(records);
+
+// Result:
+{
+  success: true,  // ✅ At least one item succeeded
+  data: [
+    { sku: 'ABC', quantity: 10 },
+    { sku: 'GHI', quantity: 20 }
+  ],
+  errors: [
+    "Failed to map field 'quantity': Required field 'quantity' is missing or empty (source: qty)",
+    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: sku)"
+  ]
+}
+```
+
+**Behavior:**
+- ✅ Successful items collected in `data` array
+- ❌ Failed items logged in `errors` array
+- Result is `success: true` if **at least one item** succeeds
+- Result is `success: false` if **all items** fail
+
+### Processing Individual Records
+
+```typescript
+// Production pattern: Process records one-by-one for detailed error tracking
+const mappedRecords = [];
+const failedRecords = [];
+
+for (let i = 0; i < records.length; i++) {
+  const record = records[i];
+  const recordId = record.sku || record.id || `index-${i}`;
+
+  const mappingResult = await mapper.map(record);
+
+  if (mappingResult.success) {
+    mappedRecords.push(mappingResult.data);
+    log.info(`✅ Record ${recordId} mapped successfully`);
+  } else {
+    failedRecords.push({
+      recordId,
+      index: i,
+      record,
+      errors: mappingResult.errors
+    });
+    log.error(`❌ Record ${recordId} mapping failed`, {
+      errors: mappingResult.errors,
+      record: JSON.stringify(record)
+    });
+  }
+}
+
+log.info('Mapping complete', {
+  total: records.length,
+  successful: mappedRecords.length,
+  failed: failedRecords.length,
+  successRate: `${((mappedRecords.length / records.length) * 100).toFixed(2)}%`
+});
+```
+
+### Nested Array Error Handling
+
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    orderId: { source: 'id', required: true },
+    items: {
+      source: 'items',
+      isArray: true,
+      fields: {
+        sku: { source: 'sku', required: true },
+        quantity: { source: 'qty', required: true }
+      }
+    }
+  }
+});
+
+const result = await mapper.map({
+  id: 'ORDER-123',
+  items: [
+    { sku: 'ABC', qty: 10 },  // ✅ Valid
+    { qty: 5 }                // ❌ Missing sku
+  ]
+});
+
+// Result:
+{
+  success: false,  // ❌ Required nested field failed
+  data: null,
+  errors: [
+    "Failed to map field 'items': Required field 'sku' is missing or empty"
+  ]
+}
+```
+
+**Nested array errors propagate up** - Parent field fails if any array item has required field errors.
+
+---
+
+## Error Result Structure
+
+Every mapping operation returns a `MappingResult`:
+
+```typescript
+interface MappingResult {
+  /** Whether mapping succeeded */
+  success: boolean;
+
+  /** Mapped data (null if failed) */
+  data: any;
+
+  /** Errors encountered during mapping */
+  errors?: string[];
+
+  /** Fields that were skipped because they were undefined (field names only) */
+  skippedFields?: string[];
+}
+```
+
+### Success Cases
+
+#### 1. Complete Success
+
+```typescript
+{
+  success: true,
+  data: { sku: 'ABC', quantity: 10 },
+  errors: undefined  // No errors
+}
+```
+
+#### 2. Success with Skipped Fields
+
+```typescript
+{
+  success: true,
+  data: { sku: 'ABC' },  // description field skipped (was undefined)
+  errors: undefined,
+  skippedFields: ['description']  // Field names that were skipped
+}
+```
+
+#### 3. Success with Resolver Errors (Optional Fields)
+
+```typescript
+{
+  success: true,
+  data: { sku: 'ABC' },
+  errors: [
+    "Failed to map field 'description': Resolver 'sdk.uppercase' failed: Cannot uppercase null"
+  ]
+}
+```
+
+### Failure Cases
+
+#### 1. Required Field Missing
+
+```typescript
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: product.sku)"
+  ]
+}
+```
+
+#### 2. Multiple Errors (Array Processing)
+
+```typescript
+{
+  success: true,  // Some items succeeded
+  data: [
+    { sku: 'ABC', quantity: 10 },
+    { sku: 'DEF', quantity: 20 }
+  ],
+  errors: [
+    "Failed to map field 'sku': Required field 'sku' is missing or empty",
+    "Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'XYZ' as integer"
+  ]
+}
+```
+
+---
+
+## Common Error Scenarios
+
+### Scenario 1: Required Field Missing
+
+**Problem:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'product.sku', required: true }
+  }
+});
+
+const result = await mapper.map({ product: {} });
+```
+
+**Error:**
+```
+Failed to map field 'sku': Required field 'sku' is missing or empty (source: product.sku)
+```
+
+**Solutions:**
+
+✅ **Option 1: Fix source data**
+```typescript
+await mapper.map({ product: { sku: 'ABC123' } });
+```
+
+✅ **Option 2: Make field optional with default**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: {
+      source: 'product.sku',
+      defaultValue: 'UNKNOWN'  // No longer required
+    }
+  }
+});
+```
+
+✅ **Option 3: Use resolver to generate value**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    sku: {
+      resolver: 'sdk.uuid',  // Generates UUID if source missing
+      required: true
+    }
+  }
+});
+```
+
+---
+
+### Scenario 2: Resolver Fails on Invalid Data
+
+**Problem:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt',
+      required: true
+    }
+  }
+});
+
+const result = await mapper.map({ qty: 'ABC' });
+```
+
+**Error:**
+```
+Failed to map field 'quantity': Resolver 'sdk.parseInt' failed: Cannot parse 'ABC' as integer
+```
+
+**Solutions:**
+
+✅ **Option 1: Fix source data**
+```typescript
+await mapper.map({ qty: '123' }); // Valid number string
+```
+
+✅ **Option 2: Use parseInt with optional field and default**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt',  // Already safe, returns 0 for invalid input
+      required: false,            // Make optional to allow default
+      defaultValue: 0             // Fallback for missing/invalid
+    }
+  }
+});
+```
+
+✅ **Option 3: Validate before mapping**
+```typescript
+const sourceData = { qty: 'ABC' };
+
+// Pre-validation
+if (!/^\d+$/.test(sourceData.qty)) {
+  throw new Error(`Invalid quantity: ${sourceData.qty}`);
+}
+
+await mapper.map(sourceData);
+```
+
+---
+
+### Scenario 3: Resolver Not Found
+
+**Problem:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    status: {
+      value: 'active',
+      resolver: 'sdk.uppercas'  // ❌ Typo: should be 'sdk.uppercase'
+    }
+  }
+});
+```
+
+**Error:**
+```
+Failed to map field 'status': Resolver 'sdk.uppercas' not found
+```
+
+**Solutions:**
+
+✅ **Option 1: Fix typo**
+```typescript
+resolver: 'sdk.uppercase'  // ✅ Correct spelling
+```
+
+✅ **Option 2: Check available resolvers**
+```typescript
+console.log(mapper.getResolverNames());
+// ['sdk.uppercase', 'sdk.lowercase', 'sdk.parseInt', ...]
+```
+
+✅ **Option 3: Register custom resolver if needed**
+```typescript
+mapper.registerResolver('custom.uppercas', (value) => {
+  return String(value).toUpperCase();
+});
+```
+
+---
+
+### Scenario 4: Contradictory Configuration
+
+**Problem:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    status: {
+      source: 'status',
+      required: true,
+      defaultValue: 'ACTIVE'  // ❌ Contradictory: required + defaultValue
+    }
+  }
+});
+```
+
+**Warning (logged to console):**
+```
+⚠️  Field 'status' has both required=true and defaultValue.
+This is contradictory - the defaultValue will never be used because required validation
+fails before defaultValue is applied. Consider using required=false if you want a fallback value.
+```
+
+**Solution:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    status: {
+      source: 'status',
+      required: false,        // ✅ Allow missing with default
+      defaultValue: 'ACTIVE'
+    }
+  }
+});
+```
+
+---
+
+### Scenario 5: Nested Required Field Missing
+
+**Problem:**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    customer: {
+      fields: {
+        email: { source: 'email', required: true },
+        phone: { source: 'phone', required: true }
+      }
+    }
+  }
+});
+
+const result = await mapper.map({
+  customer: { email: 'test@example.com' } // Missing phone
+});
+```
+
+**Error:**
+```
+Failed to map field 'phone': Required field 'phone' is missing or empty
+```
+
+**Solutions:**
+
+✅ **Option 1: Provide required field**
+```typescript
+await mapper.map({
+  customer: {
+    email: 'test@example.com',
+    phone: '555-1234'  // ✅ Provided
+  }
+});
+```
+
+✅ **Option 2: Make field optional**
+```typescript
+const mapper = new UniversalMapper({
+  fields: {
+    customer: {
+      fields: {
+        email: { source: 'email', required: true },
+        phone: { source: 'phone', required: false }  // ✅ Optional
+      }
+    }
+  }
+});
+```
+
+---
+
+## Production Patterns
+
+### Pattern 1: Individual Record Error Tracking
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+interface RecordError {
+  recordId: string;
+  index: number;
+  error: string[];
+  record: any;
+  timestamp: string;
+}
+
+async function processRecords(
+  records: any[],
+  mapper: UniversalMapper,
+  log: any
+): Promise<{
+  successful: any[];
+  failed: RecordError[];
+  summary: string;
+}> {
+  const successful = [];
+  const failed: RecordError[] = [];
+
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    const recordId = record.id || record.sku || `index-${i}`;
+
+    try {
+      const mappingResult = await mapper.map(record);
+
+      if (mappingResult.success) {
+        successful.push(mappingResult.data);
+        log.info(`✅ Record ${recordId} processed`, { index: i });
+      } else {
+        failed.push({
+          recordId,
+          index: i,
+          error: mappingResult.errors || ['Unknown error'],
+          record,
+          timestamp: new Date().toISOString()
+        });
+        log.error(`❌ Record ${recordId} failed`, {
+          index: i,
+          errors: mappingResult.errors
+        });
+      }
+    } catch (error: any) {
+      // Unexpected error (config issue, etc.)
+      failed.push({
+        recordId,
+        index: i,
+        error: [error.message],
+        record,
+        timestamp: new Date().toISOString()
+      });
+      log.error(`💥 Record ${recordId} threw exception`, {
+        error: error.message,
+        stack: error.stack
+      });
+    }
+  }
+
+  return {
+    successful,
+    failed,
+    summary: `Processed ${records.length} records: ${successful.length} succeeded, ${failed.length} failed`
+  };
+}
+```
+
+### Pattern 2: Error Categorization
+
+```typescript
+enum ErrorCategory {
+  VALIDATION = 'validation',
+  MAPPING = 'mapping',
+  RESOLVER = 'resolver',
+  UNKNOWN = 'unknown'
+}
+
+interface CategorizedError {
+  category: ErrorCategory;
+  recordId: string;
+  message: string;
+  record: any;
+}
+
+function categorizeError(error: string, record: any, recordId: string): CategorizedError {
+  if (error.includes('Required field')) {
+    return {
+      category: ErrorCategory.VALIDATION,
+      recordId,
+      message: error,
+      record
+    };
+  } else if (error.includes('Resolver')) {
+    return {
+      category: ErrorCategory.RESOLVER,
+      recordId,
+      message: error,
+      record
+    };
+  } else if (error.includes('Failed to map')) {
+    return {
+      category: ErrorCategory.MAPPING,
+      recordId,
+      message: error,
+      record
+    };
+  } else {
+    return {
+      category: ErrorCategory.UNKNOWN,
+      recordId,
+      message: error,
+      record
+    };
+  }
+}
+
+async function processWithCategorization(
+  records: any[],
+  mapper: UniversalMapper,
+  log: any
+) {
+  const results = {
+    successful: [],
+    errors: {
+      [ErrorCategory.VALIDATION]: [] as CategorizedError[],
+      [ErrorCategory.MAPPING]: [] as CategorizedError[],
+      [ErrorCategory.RESOLVER]: [] as CategorizedError[],
+      [ErrorCategory.UNKNOWN]: [] as CategorizedError[]
+    }
+  };
+
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    const recordId = record.id || `index-${i}`;
+
+    const mappingResult = await mapper.map(record);
+
+    if (mappingResult.success) {
+      results.successful.push(mappingResult.data);
+    } else {
+      // Categorize each error
+      (mappingResult.errors || []).forEach(errorMsg => {
+        const categorized = categorizeError(errorMsg, record, recordId);
+        results.errors[categorized.category].push(categorized);
+      });
+    }
+  }
+
+  // Log summary by category
+  log.info('Processing complete', {
+    successful: results.successful.length,
+    validationErrors: results.errors[ErrorCategory.VALIDATION].length,
+    mappingErrors: results.errors[ErrorCategory.MAPPING].length,
+    resolverErrors: results.errors[ErrorCategory.RESOLVER].length,
+    unknownErrors: results.errors[ErrorCategory.UNKNOWN].length
+  });
+
+  return results;
+}
+```
+
+### Pattern 3: Using PartialBatchRecovery for Retries
+
+```typescript
+import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
+
+async function processWithRecovery(
+  records: any[],
+  mapper: UniversalMapper,
+  client: FluentClient,
+  jobId: string,
+  log: any
+) {
+  const recovery = new PartialBatchRecovery(log);
+
+  const result = await recovery.processBatchWithRecovery(
+    records,
+    async (batch) => {
+      // Map records
+      const mapped = [];
+      for (const rec of batch) {
+        const mappingResult = await mapper.map(rec);
+        if (mappingResult.success) {
+          mapped.push(mappingResult.data);
+        } else {
+          throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
+        }
+      }
+
+      // Send to Fluent
+      return client.sendBatch(jobId, mapped);
+    },
+    {
+      maxRetries: 3,
+      retryOnlyFailed: true,
+      checkpointKey: `job-${jobId}`,
+      retryDelayMs: 1000
+    }
+  );
+
+  log.info('Batch processing complete', {
+    total: result.totalRecords,
+    successful: result.successCount,
+    failed: result.failedCount,
+    failedRecords: result.failedRecords
+  });
+
+  return result;
+}
+```
+
+---
+
+## Troubleshooting Guide
+
+### Quick Diagnostic Checklist
+
+When you encounter mapping errors, check:
+
+1. **✅ Is the field required?**
+   - Check `required: true` in field config
+   - Required fields must have non-null/non-empty values
+
+2. **✅ Is the source path correct?**
+   - Verify path matches actual data structure
+   - Check for typos in field names
+   - Use `console.log(JSON.stringify(sourceData))` to inspect
+
+3. **✅ Is the resolver name correct?**
+   - Check spelling: `sdk.parseInt` not `sdk.parseInt`
+   - Verify with `mapper.getResolverNames()`
+   - Ensure custom resolvers are registered
+
+4. **✅ Is the data type compatible with resolver?**
+   - `sdk.parseInt` expects string/number (returns 0 for invalid, already safe)
+   - `sdk.parseFloat` expects string/number (returns 0 for invalid, already safe)
+   - `sdk.uppercase` expects string
+   - Make fields optional with `defaultValue` for fallback behavior
+
+5. **✅ Are there nested required fields?**
+   - Check all nested field configs
+   - Nested required fields propagate errors up
+
+### Common Error Messages
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `Required field 'X' is missing or empty` | Field is null/undefined/'' | Provide value or make optional |
+| `Resolver 'X' not found` | Typo or unregistered resolver | Fix spelling or register resolver |
+| `Resolver 'X' failed: ...` | Resolver threw during execution | Fix input data or use safe resolver |
+| `Failed to map field 'X': ...` | Generic mapping failure | Check field config and data |
+
+### Debug Logging
+
+```typescript
+const mockLogger = {
+  info: (...args: any[]) => console.log('[INFO]', ...args),
+  debug: (...args: any[]) => console.log('[DEBUG]', ...args),
+  warn: (...args: any[]) => console.warn('[WARN]', ...args),
+  error: (...args: any[]) => console.error('[ERROR]', ...args)
+};
+
+const mapper = new UniversalMapper(config, { logger: mockLogger });
+
+// Now see detailed logs during mapping
+const result = await mapper.map(data);
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+
+1. **Always check `mappingResult.success`**
+   ```typescript
+   if (mappingResult.success) {
+     await client.sendBatch(jobId, mappingResult.data);
+   } else {
+     log.error('Mapping failed', mappingResult.errors);
+   }
+   ```
+
+2. **Log detailed error context**
+   ```typescript
+   log.error('Record mapping failed', {
+     recordId,
+     errors: mappingResult.errors,
+     record: JSON.stringify(record)
+   });
+   ```
+
+3. **Use optional fields with defaults for non-critical data**
+   ```typescript
+   description: { source: 'desc', defaultValue: '' }
+   ```
+
+4. **Process records individually for better error tracking**
+   ```typescript
+   for (const record of records) {
+     const result = await mapper.map(record);
+     // Handle individually
+   }
+   ```
+
+5. **Categorize errors for monitoring**
+   ```typescript
+   if (error.includes('Resolver')) {
+     metrics.incrementResolverErrors();
+   }
+   ```
+
+### ❌ DON'T:
+
+1. **Don't ignore `mappingResult.errors`**
+   ```typescript
+   // ❌ BAD
+   const result = await mapper.map(data);
+   await client.sendBatch(jobId, result.data); // Might be null!
+
+   // ✅ GOOD
+   if (result.success) {
+     await client.sendBatch(jobId, result.data);
+   }
+   ```
+
+2. **Don't use required + defaultValue together**
+   ```typescript
+   // ❌ BAD - defaultValue never used
+   { source: 'field', required: true, defaultValue: 'X' }
+
+   // ✅ GOOD - Optional with default
+   { source: 'field', required: false, defaultValue: 'X' }
+   ```
+
+3. **Don't catch and ignore errors silently**
+   ```typescript
+   // ❌ BAD
+   try {
+     await mapper.map(record);
+   } catch (error) {
+     // Silently ignored
+   }
+
+   // ✅ GOOD
+   try {
+     const result = await mapper.map(record);
+     if (!result.success) {
+       log.error('Mapping failed', result.errors);
+     }
+   } catch (error) {
+     log.error('Unexpected error', error);
+   }
+   ```
+
+4. **Don't assume all array items succeed**
+   ```typescript
+   // ❌ BAD
+   const result = await mapper.map(records);
+   console.log(`Processed ${records.length} records`);
+
+   // ✅ GOOD
+   const result = await mapper.map(records);
+   console.log(`Processed ${result.data.length}/${records.length} records`);
+   if (result.errors) {
+     console.log(`Errors: ${result.errors.length}`);
+   }
+   ```
+
+---
+
+## Related Documentation
+
+- [Mapping Foundations](./mapping-01-foundations.md) - Core mapping concepts
+- [Custom Resolvers](../resolvers/mapping-resolvers-resolver-guide.md) - Building custom resolvers
+- [Error Handling Pattern Guide](../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - General error handling
+- [GraphQL Mutation Mapper Error Handling](../graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md) - GraphQL-specific errors
+
+---
+
+## Summary
+
+**Key Takeaways:**
+
+1. ✅ **UniversalMapper provides built-in error handling** - No need to wrap each record in try-catch
+2. ✅ **Required fields fail-fast** - Prevents partial/corrupt data
+3. ✅ **Optional fields continue with warnings** - Flexible error handling
+4. ✅ **Array processing is automatic** - Each item processed individually
+5. ✅ **Rich error context** - Field name, source path, resolver name, input value
+6. ✅ **MappingResult tells you everything** - `success`, `data`, `errors`
+
+**Next Steps:**
+
+- Try the [Error Scenarios Test Suite](../../../../tests/unit/services/mapping/universal-mapper.test.ts)
+- Review [Production Templates](../../../01-TEMPLATES/) for real-world examples
+- Check [Resolver Troubleshooting](../resolvers/mapping-resolvers-resolver-troubleshooting.md) for resolver-specific issues
+
+---
+
+[← Back to Mapping Guide](../mapping-readme.md)