@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md

@@ -1,488 +1,488 @@
-# Error Handling
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 11 of 13** | **Level**: Intermediate | **Time**: 20 minutes
-
----
-
-## Error Handling
-
-Understanding error handling is critical for building robust integrations. The GraphQL Mutation Mapper provides fail-fast error handling to prevent partial data corruption.
-
-## Fail-Fast Behavior
-
-The GraphQL Mutation Mapper implements **fail-fast error handling** - if ANY error occurs during mapping or validation, the GraphQL mutation is **NEVER SENT** to Fluent Commerce.
-
-```
-Parse Source Data
-  ↓ (throws FileParsingError if invalid)
-Resolve Paths
-  ↓ (throws PathResolutionError if path not found)
-Map Fields
-  ↓ (throws MappingError if required field missing)
-Validate Data
-  ↓ (throws ValidationError if validation fails)
-Execute GraphQL Mutation
-  ↓ (never reached if any error above)
-✅ ALL DATA COMMITTED or ❌ NO DATA COMMITTED
-```
-
-**Key Benefits:**
-
-- ✅ **No partial data**: Either complete order is created or nothing
-- ✅ **Data integrity**: No orphaned records or inconsistent state
-- ✅ **Clear errors**: Know exactly what went wrong and where
-- ✅ **Easy rollback**: Nothing to roll back - mutation never executed
-
-## Error Types
-
-### PathResolutionError
-
-Thrown when source path doesn't exist in data.
-
-```typescript
-// Mapping config
-{
-  "ref": {
-    "source": "order.WRONG_PATH.customer-email",
-    "required": true
-  }
-}
-
-// Result
-PathResolutionError: Cannot resolve path 'order.WRONG_PATH.customer-email'
-  path: "order.WRONG_PATH.customer-email"
-```
-
-**Impact**: ✅ Mutation **NEVER EXECUTED** - No data created
-
-**Common Causes:**
-
-- Typo in path expression
-- Source data structure changed
-- Path assumes array but got object
-- Attribute access syntax error (e.g., `element.@attr` instead of `element@attr`)
-
-### MappingError
-
-Thrown when field mapping fails.
-
-```typescript
-// Mapping config
-{
-  "ref": {
-    "source": "order.missing-field",
-    "required": true
-  }
-}
-
-// Result
-MappingError: Required field 'ref' is missing or empty
-  field: "ref"
-  sourcePath: "order.missing-field"
-```
-
-**Impact**: ✅ Mutation **NEVER EXECUTED** - No data created
-
-**Common Causes:**
-
-- Required field is null/undefined/empty string
-- Array validation failed (minItems, maxItems)
-- Type conversion failed
-- Custom resolver threw error
-
-### FileParsingError
-
-Thrown when XML/JSON parsing fails.
-
-```typescript
-// Invalid XML
-<order>
-  <customer-email>test@example.com
-  <!-- Missing closing tag -->
-
-// Result
-FileParsingError: Failed to parse XML: Mismatched opening and closing tags
-  fileName: "order.xml"
-  code: PARSE_ERROR
-```
-
-**Impact**: ✅ Mutation **NEVER ATTEMPTED** - No data created
-
-**Common Causes:**
-
-- Malformed XML (unclosed tags, invalid characters)
-- Invalid JSON (trailing commas, unquoted keys)
-- Encoding issues (UTF-8 vs Latin-1)
-- File corruption
-
-## Error Scenarios
-
-### Scenario 1: Wrong Source Path
-
-```json
-{
-  "email": {
-    "source": "customer.WRONG_PATH.email",
-    "required": true
-  }
-}
-```
-
-**Result**: `PathResolutionError` - Mutation never sent
-
-**Solution:**
-
-```json
-{
-  "email": {
-    "source": "customer.email", // ✅ Correct path
-    "required": true
-  }
-}
-```
-
-### Scenario 2: Type Mismatch
-
-```json
-{
-  "quantity": {
-    "source": "quantity",
-    "resolver": "sdk.parseInt" // But source is "abc"
-  }
-}
-```
-
-**Result**: `NaN` value → GraphQL rejects with type error
-
-**Solution:**
-
-```json
-{
-  "quantity": {
-    "source": "quantity",
-    "resolver": "sdk.parseInt", // ✅ Safe parsing with default
-    "defaultValue": 1
-  }
-}
-```
-
-### Scenario 3: Required Field with Resolver Returning Empty Value
-
-**Problem:** Resolver-only field with `required: true` returns empty value
-
-```json
-{
-  "customerId": {
-    "resolver": "custom.lookupCustomer",
-    "required": true
-  }
-}
-```
-
-```typescript
-'custom.lookupCustomer': async (value, data, config, helpers) => {
-  const email = helpers.get(data, 'customer.email');
-  const customer = await lookupCustomerByEmail(email);
-  return customer?.id; // ❌ Returns undefined if customer not found
-}
-```
-
-**Result**: `MappingError: Required field 'customerId' is missing or empty after resolver 'custom.lookupCustomer' execution`
-
-**Solution 1:** Ensure resolver always returns a value or throws:
-
-```typescript
-'custom.lookupCustomer': async (value, data, config, helpers) => {
-  const email = helpers.get(data, 'customer.email');
-  if (!email) {
-    throw new Error('Email required for customer lookup');
-  }
-  const customer = await lookupCustomerByEmail(email);
-  if (!customer) {
-    throw new Error(`Customer not found for email: ${email}`);
-  }
-  return customer.id; // ✅ Always returns a value or throws
-}
-```
-
-**Solution 2:** Use `defaultValue` with resolver:
-
-```json
-{
-  "customerId": {
-    "resolver": "custom.lookupCustomer",
-    "required": true,
-    "defaultValue": "UNKNOWN"  // Fallback if resolver returns empty
-  }
-}
-```
-
-**Note:** Validation timing for `required` fields:
-- Fields with `source`: Validated **before** resolver execution
-- Resolver-only fields (no `source`): Validated **after** resolver execution
-
-### Scenario 4: Array Validation Failure
-
-```json
-{
-  "items": {
-    "_array": true,
-    "_validation": { "minItems": 1 },
-    "source": "items"
-  }
-}
-```
-
-**Result** (if empty): `MappingError: Array must have at least 1 items` - Mutation never sent
-
-**Solution:**
-
-- Ensure source data always has items
-- Or remove `minItems` validation if empty arrays are allowed
-- Or provide default: `"defaultValue": []`
-
-### Scenario 4: GraphQL Schema Mismatch
-
-```json
-{
-  "INVALID_FIELD": "value" // Not in schema
-}
-```
-
-**Result**: Mutation sent but **rejected by Fluent** with GraphQL validation error
-
-**Solution:**
-
-- Run schema introspection: `npx fc-connect introspect-schema`
-- Validate mapping: `npx fc-connect validate-schema`
-- Fix field names to match schema exactly
-
-## Error Handling Patterns
-
-### Basic Error Handling
-
-```typescript
-import {
-  XMLParserService,
-  GraphQLMutationMapper,
-  FileParsingError,
-  PathResolutionError,
-  MappingError,
-  classifyErrors,
-} from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  // Parse source data
-  const parser = new XMLParserService();
-  const parsed = await parser.parse(xmlContent);
-
-  // Map to mutation
-  const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
-  const payload = await mapper.map(parsed);
-
-  // Execute mutation
-  const result = await client.graphql(payload);
-
-  if (result.errors) {
-    // Classify GraphQL errors to determine if retryable
-    const classification = classifyErrors(result.errors);
-    
-    logger.error('GraphQL error:', {
-      errorCode: classification.errorCode,
-      message: classification.userMessage,
-      retryable: classification.retryable,
-      action: classification.action,
-    });
-    
-    if (!classification.retryable) {
-      throw new Error(classification.userMessage);
-    }
-    // Retry logic would go here for retryable errors
-    throw new Error(classification.userMessage);
-  }
-
-  return result.data; // ✅ Complete data or nothing
-} catch (error) {
-  if (error instanceof FileParsingError) {
-    // XML/JSON parsing failed
-    console.error('Parse error:', {
-      code: error.code,
-      fileName: error.fileName,
-      message: error.message,
-    });
-    // Alert user: Invalid file
-  } else if (error instanceof PathResolutionError) {
-    // Wrong path in mapping config
-    console.error('Path error:', {
-      path: error.path,
-      message: error.message,
-    });
-    // Alert developer: Fix mapping config
-  } else if (error instanceof MappingError) {
-    // Required field missing or validation failed
-    console.error('Mapping error:', {
-      field: error.field,
-      sourcePath: error.sourcePath,
-      message: error.message,
-    });
-    // Alert developer: Data doesn't match mapping
-  }
-
-  throw error; // ✅ Re-throw to prevent silent failures
-}
-```
-
-### Error Handling with Retry Logic
-
-```typescript
-async function mapWithRetry(sourceData: any, maxRetries = 3) {
-  let attempt = 0;
-
-  while (attempt < maxRetries) {
-    try {
-      attempt++;
-      const payload = await mapper.map(sourceData);
-      return payload;
-    } catch (error) {
-      // Check if error is retryable
-      if (
-        error instanceof PathResolutionError ||
-        error instanceof MappingError ||
-        error instanceof FileParsingError
-      ) {
-        // These are permanent errors - don't retry
-        throw error;
-      }
-
-      // Check if error is from Fluent (might be transient)
-      if (error.message?.includes('timeout') || error.message?.includes('network')) {
-        if (attempt < maxRetries) {
-          console.log(`Retry ${attempt}/${maxRetries}`);
-          await delay(1000 * attempt);
-          continue;
-        }
-      }
-
-      throw error;
-    }
-  }
-
-  throw new Error('Max retries exceeded');
-}
-```
-
-### Common Error Messages
-
-| Error                                           | Meaning                                | Solution                                    |
-| ----------------------------------------------- | -------------------------------------- | ------------------------------------------- |
-| `Required field 'ref' is missing or empty`      | Required field has no value            | Check source data or add defaultValue       |
-| `Required field 'X' is missing or empty after resolver 'Y' execution` | Resolver-only required field returned empty | Fix resolver to always return value or throw |
-| `Expected array but got object at path 'items'` | Source is object not array             | Add `_autoWrap: true` or fix source path    |
-| `Array must have at least 1 item`               | Array is empty but minItems validation | Ensure data has required items              |
-| `Cannot resolve path 'order.missing'`           | Path doesn't exist in source           | Fix mapping configuration path              |
-| `Type mismatch: expected Int! but got String`   | Wrong data type                        | Add transform (parseInt) or fix source data |
-
-### Error Recovery
-
-```typescript
-class MappingErrorHandler {
-  async handleError(error: Error, context: any): Promise<void> {
-    if (error instanceof PathResolutionError) {
-      // Log configuration error
-      logger.error('Mapping configuration error:', {
-        path: error.path,
-        sourceFile: context.fileName,
-        mappingConfig: context.mappingName,
-      });
-
-      // Alert developer
-      await sendAlert({
-        type: 'CONFIG_ERROR',
-        severity: 'HIGH',
-        message: `Mapping path '${error.path}' not found in source data`,
-        action: 'Fix mapping configuration',
-      });
-    } else if (error instanceof MappingError) {
-      // Log data quality issue
-      logger.error('Data quality error:', {
-        field: error.field,
-        sourcePath: error.sourcePath,
-        sourceFile: context.fileName,
-      });
-
-      // Alert data team
-      await sendAlert({
-        type: 'DATA_QUALITY',
-        severity: 'MEDIUM',
-        message: `Required field '${error.field}' missing in source data`,
-        action: 'Check source data format',
-      });
-    }
-  }
-}
-```
-
-### Error Logging Best Practices
-
-```typescript
-try {
-  const payload = await mapper.map(sourceData);
-  const result = await client.graphql(payload);
-
-  // Log success
-  logger.info('Order created successfully', {
-    orderRef: result.data.createOrder.ref,
-    orderId: result.data.createOrder.id,
-    itemCount: payload.variables.input.items.length,
-  });
-} catch (error) {
-  // Log error with context
-  logger.error('Order creation failed', {
-    error: error.message,
-    errorType: error.constructor.name,
-    sourceFile: context.fileName,
-    mappingConfig: context.mappingName,
-    // Include sanitized source data (remove PII)
-    sourceData: sanitizeForLogging(sourceData),
-  });
-
-  throw error;
-}
-```
-
-## Best Practices
-
-1. **Always wrap mapping in try-catch** - Never let errors go unhandled
-2. **Check error types with instanceof** - Handle different errors appropriately
-3. **Log error context** - Include field names, paths, and source files
-4. **Don't retry permanent errors** - PathResolutionError, MappingError, FileParsingError
-5. **Re-throw after handling** - Prevent silent failures
-6. **Monitor error patterns** - Track error frequencies and alert on anomalies
-7. **Test error paths** - Ensure your error handling works correctly
-
-### Error Handling Checklist
-
-- [ ] Wrap all mapping calls in try-catch
-- [ ] Handle FileParsingError (invalid source data)
-- [ ] Handle PathResolutionError (wrong mapping config)
-- [ ] Handle MappingError (data validation failures)
-- [ ] Log errors with context (file name, field, path)
-- [ ] Alert appropriate teams (developers vs data teams)
-- [ ] Don't retry permanent errors
-- [ ] Re-throw errors to prevent silent failures
-- [ ] Test error scenarios with invalid data
-
----
-
-## Navigation
-
-[← Previous: Hooks and Variables](./graphql-mutation-mapping-10-hooks-and-variables.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Arguments vs Nodes →](./graphql-mutation-mapping-12-arguments-vs-nodes.md)
-
-## Related Documentation
-
-- [Complete Error Handling Guide](../../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Comprehensive error handling documentation
-- [Error Handling Guide](../../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Error handling patterns and retry strategies
-- [API Reference](../../../api-reference/api-reference-readme.md) - Complete error class documentation
-- [Module 10: Hooks and Variables](./graphql-mutation-mapping-10-hooks-and-variables.md) - Pre/post-processing hooks
+# Error Handling
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 11 of 13** | **Level**: Intermediate | **Time**: 20 minutes
+
+---
+
+## Error Handling
+
+Understanding error handling is critical for building robust integrations. The GraphQL Mutation Mapper provides fail-fast error handling to prevent partial data corruption.
+
+## Fail-Fast Behavior
+
+The GraphQL Mutation Mapper implements **fail-fast error handling** - if ANY error occurs during mapping or validation, the GraphQL mutation is **NEVER SENT** to Fluent Commerce.
+
+```
+Parse Source Data
+  ↓ (throws FileParsingError if invalid)
+Resolve Paths
+  ↓ (throws PathResolutionError if path not found)
+Map Fields
+  ↓ (throws MappingError if required field missing)
+Validate Data
+  ↓ (throws ValidationError if validation fails)
+Execute GraphQL Mutation
+  ↓ (never reached if any error above)
+✅ ALL DATA COMMITTED or ❌ NO DATA COMMITTED
+```
+
+**Key Benefits:**
+
+- ✅ **No partial data**: Either complete order is created or nothing
+- ✅ **Data integrity**: No orphaned records or inconsistent state
+- ✅ **Clear errors**: Know exactly what went wrong and where
+- ✅ **Easy rollback**: Nothing to roll back - mutation never executed
+
+## Error Types
+
+### PathResolutionError
+
+Thrown when source path doesn't exist in data.
+
+```typescript
+// Mapping config
+{
+  "ref": {
+    "source": "order.WRONG_PATH.customer-email",
+    "required": true
+  }
+}
+
+// Result
+PathResolutionError: Cannot resolve path 'order.WRONG_PATH.customer-email'
+  path: "order.WRONG_PATH.customer-email"
+```
+
+**Impact**: ✅ Mutation **NEVER EXECUTED** - No data created
+
+**Common Causes:**
+
+- Typo in path expression
+- Source data structure changed
+- Path assumes array but got object
+- Attribute access syntax error (e.g., `element.@attr` instead of `element@attr`)
+
+### MappingError
+
+Thrown when field mapping fails.
+
+```typescript
+// Mapping config
+{
+  "ref": {
+    "source": "order.missing-field",
+    "required": true
+  }
+}
+
+// Result
+MappingError: Required field 'ref' is missing or empty
+  field: "ref"
+  sourcePath: "order.missing-field"
+```
+
+**Impact**: ✅ Mutation **NEVER EXECUTED** - No data created
+
+**Common Causes:**
+
+- Required field is null/undefined/empty string
+- Array validation failed (minItems, maxItems)
+- Type conversion failed
+- Custom resolver threw error
+
+### FileParsingError
+
+Thrown when XML/JSON parsing fails.
+
+```typescript
+// Invalid XML
+<order>
+  <customer-email>test@example.com
+  <!-- Missing closing tag -->
+
+// Result
+FileParsingError: Failed to parse XML: Mismatched opening and closing tags
+  fileName: "order.xml"
+  code: PARSE_ERROR
+```
+
+**Impact**: ✅ Mutation **NEVER ATTEMPTED** - No data created
+
+**Common Causes:**
+
+- Malformed XML (unclosed tags, invalid characters)
+- Invalid JSON (trailing commas, unquoted keys)
+- Encoding issues (UTF-8 vs Latin-1)
+- File corruption
+
+## Error Scenarios
+
+### Scenario 1: Wrong Source Path
+
+```json
+{
+  "email": {
+    "source": "customer.WRONG_PATH.email",
+    "required": true
+  }
+}
+```
+
+**Result**: `PathResolutionError` - Mutation never sent
+
+**Solution:**
+
+```json
+{
+  "email": {
+    "source": "customer.email", // ✅ Correct path
+    "required": true
+  }
+}
+```
+
+### Scenario 2: Type Mismatch
+
+```json
+{
+  "quantity": {
+    "source": "quantity",
+    "resolver": "sdk.parseInt" // But source is "abc"
+  }
+}
+```
+
+**Result**: `NaN` value → GraphQL rejects with type error
+
+**Solution:**
+
+```json
+{
+  "quantity": {
+    "source": "quantity",
+    "resolver": "sdk.parseInt", // ✅ Safe parsing with default
+    "defaultValue": 1
+  }
+}
+```
+
+### Scenario 3: Required Field with Resolver Returning Empty Value
+
+**Problem:** Resolver-only field with `required: true` returns empty value
+
+```json
+{
+  "customerId": {
+    "resolver": "custom.lookupCustomer",
+    "required": true
+  }
+}
+```
+
+```typescript
+'custom.lookupCustomer': async (value, data, config, helpers) => {
+  const email = helpers.get(data, 'customer.email');
+  const customer = await lookupCustomerByEmail(email);
+  return customer?.id; // ❌ Returns undefined if customer not found
+}
+```
+
+**Result**: `MappingError: Required field 'customerId' is missing or empty after resolver 'custom.lookupCustomer' execution`
+
+**Solution 1:** Ensure resolver always returns a value or throws:
+
+```typescript
+'custom.lookupCustomer': async (value, data, config, helpers) => {
+  const email = helpers.get(data, 'customer.email');
+  if (!email) {
+    throw new Error('Email required for customer lookup');
+  }
+  const customer = await lookupCustomerByEmail(email);
+  if (!customer) {
+    throw new Error(`Customer not found for email: ${email}`);
+  }
+  return customer.id; // ✅ Always returns a value or throws
+}
+```
+
+**Solution 2:** Use `defaultValue` with resolver:
+
+```json
+{
+  "customerId": {
+    "resolver": "custom.lookupCustomer",
+    "required": true,
+    "defaultValue": "UNKNOWN"  // Fallback if resolver returns empty
+  }
+}
+```
+
+**Note:** Validation timing for `required` fields:
+- Fields with `source`: Validated **before** resolver execution
+- Resolver-only fields (no `source`): Validated **after** resolver execution
+
+### Scenario 4: Array Validation Failure
+
+```json
+{
+  "items": {
+    "_array": true,
+    "_validation": { "minItems": 1 },
+    "source": "items"
+  }
+}
+```
+
+**Result** (if empty): `MappingError: Array must have at least 1 items` - Mutation never sent
+
+**Solution:**
+
+- Ensure source data always has items
+- Or remove `minItems` validation if empty arrays are allowed
+- Or provide default: `"defaultValue": []`
+
+### Scenario 4: GraphQL Schema Mismatch
+
+```json
+{
+  "INVALID_FIELD": "value" // Not in schema
+}
+```
+
+**Result**: Mutation sent but **rejected by Fluent** with GraphQL validation error
+
+**Solution:**
+
+- Run schema introspection: `npx fc-connect introspect-schema`
+- Validate mapping: `npx fc-connect validate-schema`
+- Fix field names to match schema exactly
+
+## Error Handling Patterns
+
+### Basic Error Handling
+
+```typescript
+import {
+  XMLParserService,
+  GraphQLMutationMapper,
+  FileParsingError,
+  PathResolutionError,
+  MappingError,
+  classifyErrors,
+} from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  // Parse source data
+  const parser = new XMLParserService();
+  const parsed = await parser.parse(xmlContent);
+
+  // Map to mutation
+  const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
+  const payload = await mapper.map(parsed);
+
+  // Execute mutation
+  const result = await client.graphql(payload);
+
+  if (result.errors) {
+    // Classify GraphQL errors to determine if retryable
+    const classification = classifyErrors(result.errors);
+    
+    logger.error('GraphQL error:', {
+      errorCode: classification.errorCode,
+      message: classification.userMessage,
+      retryable: classification.retryable,
+      action: classification.action,
+    });
+    
+    if (!classification.retryable) {
+      throw new Error(classification.userMessage);
+    }
+    // Retry logic would go here for retryable errors
+    throw new Error(classification.userMessage);
+  }
+
+  return result.data; // ✅ Complete data or nothing
+} catch (error) {
+  if (error instanceof FileParsingError) {
+    // XML/JSON parsing failed
+    console.error('Parse error:', {
+      code: error.code,
+      fileName: error.fileName,
+      message: error.message,
+    });
+    // Alert user: Invalid file
+  } else if (error instanceof PathResolutionError) {
+    // Wrong path in mapping config
+    console.error('Path error:', {
+      path: error.path,
+      message: error.message,
+    });
+    // Alert developer: Fix mapping config
+  } else if (error instanceof MappingError) {
+    // Required field missing or validation failed
+    console.error('Mapping error:', {
+      field: error.field,
+      sourcePath: error.sourcePath,
+      message: error.message,
+    });
+    // Alert developer: Data doesn't match mapping
+  }
+
+  throw error; // ✅ Re-throw to prevent silent failures
+}
+```
+
+### Error Handling with Retry Logic
+
+```typescript
+async function mapWithRetry(sourceData: any, maxRetries = 3) {
+  let attempt = 0;
+
+  while (attempt < maxRetries) {
+    try {
+      attempt++;
+      const payload = await mapper.map(sourceData);
+      return payload;
+    } catch (error) {
+      // Check if error is retryable
+      if (
+        error instanceof PathResolutionError ||
+        error instanceof MappingError ||
+        error instanceof FileParsingError
+      ) {
+        // These are permanent errors - don't retry
+        throw error;
+      }
+
+      // Check if error is from Fluent (might be transient)
+      if (error.message?.includes('timeout') || error.message?.includes('network')) {
+        if (attempt < maxRetries) {
+          console.log(`Retry ${attempt}/${maxRetries}`);
+          await delay(1000 * attempt);
+          continue;
+        }
+      }
+
+      throw error;
+    }
+  }
+
+  throw new Error('Max retries exceeded');
+}
+```
+
+### Common Error Messages
+
+| Error                                           | Meaning                                | Solution                                    |
+| ----------------------------------------------- | -------------------------------------- | ------------------------------------------- |
+| `Required field 'ref' is missing or empty`      | Required field has no value            | Check source data or add defaultValue       |
+| `Required field 'X' is missing or empty after resolver 'Y' execution` | Resolver-only required field returned empty | Fix resolver to always return value or throw |
+| `Expected array but got object at path 'items'` | Source is object not array             | Add `_autoWrap: true` or fix source path    |
+| `Array must have at least 1 item`               | Array is empty but minItems validation | Ensure data has required items              |
+| `Cannot resolve path 'order.missing'`           | Path doesn't exist in source           | Fix mapping configuration path              |
+| `Type mismatch: expected Int! but got String`   | Wrong data type                        | Add transform (parseInt) or fix source data |
+
+### Error Recovery
+
+```typescript
+class MappingErrorHandler {
+  async handleError(error: Error, context: any): Promise<void> {
+    if (error instanceof PathResolutionError) {
+      // Log configuration error
+      logger.error('Mapping configuration error:', {
+        path: error.path,
+        sourceFile: context.fileName,
+        mappingConfig: context.mappingName,
+      });
+
+      // Alert developer
+      await sendAlert({
+        type: 'CONFIG_ERROR',
+        severity: 'HIGH',
+        message: `Mapping path '${error.path}' not found in source data`,
+        action: 'Fix mapping configuration',
+      });
+    } else if (error instanceof MappingError) {
+      // Log data quality issue
+      logger.error('Data quality error:', {
+        field: error.field,
+        sourcePath: error.sourcePath,
+        sourceFile: context.fileName,
+      });
+
+      // Alert data team
+      await sendAlert({
+        type: 'DATA_QUALITY',
+        severity: 'MEDIUM',
+        message: `Required field '${error.field}' missing in source data`,
+        action: 'Check source data format',
+      });
+    }
+  }
+}
+```
+
+### Error Logging Best Practices
+
+```typescript
+try {
+  const payload = await mapper.map(sourceData);
+  const result = await client.graphql(payload);
+
+  // Log success
+  logger.info('Order created successfully', {
+    orderRef: result.data.createOrder.ref,
+    orderId: result.data.createOrder.id,
+    itemCount: payload.variables.input.items.length,
+  });
+} catch (error) {
+  // Log error with context
+  logger.error('Order creation failed', {
+    error: error.message,
+    errorType: error.constructor.name,
+    sourceFile: context.fileName,
+    mappingConfig: context.mappingName,
+    // Include sanitized source data (remove PII)
+    sourceData: sanitizeForLogging(sourceData),
+  });
+
+  throw error;
+}
+```
+
+## Best Practices
+
+1. **Always wrap mapping in try-catch** - Never let errors go unhandled
+2. **Check error types with instanceof** - Handle different errors appropriately
+3. **Log error context** - Include field names, paths, and source files
+4. **Don't retry permanent errors** - PathResolutionError, MappingError, FileParsingError
+5. **Re-throw after handling** - Prevent silent failures
+6. **Monitor error patterns** - Track error frequencies and alert on anomalies
+7. **Test error paths** - Ensure your error handling works correctly
+
+### Error Handling Checklist
+
+- [ ] Wrap all mapping calls in try-catch
+- [ ] Handle FileParsingError (invalid source data)
+- [ ] Handle PathResolutionError (wrong mapping config)
+- [ ] Handle MappingError (data validation failures)
+- [ ] Log errors with context (file name, field, path)
+- [ ] Alert appropriate teams (developers vs data teams)
+- [ ] Don't retry permanent errors
+- [ ] Re-throw errors to prevent silent failures
+- [ ] Test error scenarios with invalid data
+
+---
+
+## Navigation
+
+[← Previous: Hooks and Variables](./graphql-mutation-mapping-10-hooks-and-variables.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Arguments vs Nodes →](./graphql-mutation-mapping-12-arguments-vs-nodes.md)
+
+## Related Documentation
+
+- [Complete Error Handling Guide](../../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Comprehensive error handling documentation
+- [Error Handling Guide](../../../../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) - Error handling patterns and retry strategies
+- [API Reference](../../../api-reference/api-reference-readme.md) - Complete error class documentation
+- [Module 10: Hooks and Variables](./graphql-mutation-mapping-10-hooks-and-variables.md) - Pre/post-processing hooks