/error-handling

name: error-handling-fundamentals
description: Guides error handling for async operations and API calls. Use when junior asks "what if this fails", "handle errors", "try catch", "network error", or builds features with fetch, promises, or external services.

Error Handling Fundamentals Review

> "Errors are not failures — they're information. Handle them like the valuable data they are."

When to Apply

Activate this skill when reviewing:

• try/catch blocks
• Promise chains (.then/.catch)
• API error responses
• Form validation
• Network request handling
• User-facing error messages

---

Review Checklist

Error Catching

• [ ] **No empty catches**: Is every catch block doing something meaningful?
• [ ] **Proper scope**: Are errors caught at the right level?
• [ ] **Context added**: Do errors include helpful debugging info?
• [ ] **Finally used**: Are cleanup operations in finally blocks?

User Experience

• [ ] **User-friendly messages**: Will users understand the error?
• [ ] **No technical details exposed**: Are stack traces hidden from users?
• [ ] **Actionable feedback**: Does the error tell users what to do next?
• [ ] **Graceful degradation**: Does the app still work partially on error?

Logging & Debugging

• [ ] **Errors logged**: Are errors recorded for debugging?
• [ ] **Context in logs**: Do logs include request ID, user ID, etc.?
• [ ] **Severity levels**: Are critical errors distinguished from warnings?

Recovery

• [ ] **Retry logic**: Should this operation retry on failure?
• [ ] **Fallback values**: Is there a sensible default on error?
• [ ] **Loading states**: Is the user informed while retrying?

---

Common Mistakes (Anti-Patterns)

1. The Empty Catch (The Silent Killer)

❌ try {
     await submitForm();
   } catch (error) {
     // TODO: handle later (never happens)
   }

✅ try {
     await submitForm();
   } catch (error) {
     console.error('Form submission failed:', error);
     setError('Could not submit. Please try again.');
   }

2. Catching Too Early

❌ function getUser(id) {
     try {
       return database.query(id);
     } catch {
       return null; // Caller has no idea it failed
     }
   }

✅ function getUser(id) {
     return database.query(id); // Let caller decide
   }

   // In UI layer
   try {
     const user = await getUser(id);
   } catch (error) {
     showToast('Could not load user');
   }

3. Generic Error Messages

❌ catch (error) {
     setError('An error occurred');
   }

✅ catch (error) {
     if (error.code === 'NETWORK_ERROR') {
       setError('Check your internet connection');
     } else if (error.code === 'NOT_FOUND') {
       setError('User not found');
     } else {
       setError('Something went wrong. Please try again.');
     }
   }

4. Leaking Stack Traces

❌ res.status(500).json({
     error: error.message,
     stack: error.stack
   });

✅ logger.error('Request failed', { error, requestId });
   res.status(500).json({
     error: 'Something went wrong'
   });

5. Forgetting Finally

❌ try {
     setLoading(true);
     await fetchData();
     setLoading(false);
   } catch (error) {
     handleError(error);
     // Loading stays true forever!
   }

✅ try {
     setLoading(true);
     await fetchData();
   } catch (error) {
     handleError(error);
   } finally {
     setLoading(false); // Always runs
   }

---

Socratic Questions

Ask the junior these questions instead of giving answers:

1. **Empty Catch**: "What happens if this fails silently?" 2. **User Message**: "If you were the user, would this message help you?" 3. **Recovery**: "Should we retry this automatically?" 4. **Scope**: "Is this the right place to catch this error?" 5. **Logging**: "How will you debug this in production?"

---

Error Message Guidelines

Do

• Be specific: "The email address is already registered"
• Be helpful: "Please check your internet connection"
• Offer next steps: "Try again" or "Contact support"
• Match severity: Critical errors need more attention than warnings

Don't

• Show technical details: `TypeError: Cannot read property 'map' of undefined`
• Be vague: "An error occurred"
• Blame the user: "You entered invalid data"
• Use jargon: "HTTP 500 Internal Server Error"

---

Error Handling Patterns

API/Network Errors

async function fetchWithRetry(url: string, retries = 3): Promise<Response> {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return response;
  } catch (error) {
    if (retries > 0) {
      await sleep(1000);
      return fetchWithRetry(url, retries - 1);
    }
    throw error;
  }
}

Form Validation

function validateForm(data: FormData) {
  const errors: Record<string, string> = {};

  if (!data.email) {
    errors.email = 'Email is required';
  } else if (!isValidEmail(data.email)) {
    errors.email = 'Please enter a valid email';
  }

  return {
    isValid: Object.keys(errors).length === 0,
    errors
  };
}

React Error Boundaries

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, info) {
    logError(error, info);
  }

  render() {
    if (this.state.hasError) {
      return <FallbackUI />;
    }
    return this.props.children;
  }
}

---

Standards Reference

See detailed patterns in:

• `/standards/global/error-handling.md`

---

Red Flags to Call Out

| Flag | Question to Ask | |------|-----------------| | Empty catch block | "What happens when this fails?" | | `catch (e) { return null }` | "How will the caller know it failed?" | | No loading state | "What does the user see while waiting?" | | Technical error shown | "Will the user understand this message?" | | No finally for cleanup | "Is loading state stuck on error?" | |