fvtt-error-handling

# Foundry VTT Error Handling Patterns

**Domain:** Foundry VTT V12/V13 Error Handling
**Status:** Production-Ready (Verified against V13 API)
**Last Updated:** 2025-12-31

---

## Overview

This skill provides **production-ready error handling patterns** for Foundry VTT modules, using the documented V13 APIs: `NotificationOptions` and `Hooks.onError`.

### When to Use This Skill

- Adding error handling to catch blocks in Foundry modules
- Standardizing error handling across a codebase
- Ensuring proper UX (user messages vs technical logs)
- Preventing console noise and double-logging
- Enabling ecosystem compatibility (other modules can listen to your errors)

### Core Principle

**Always separate error funnel from user notification:**

- **Error funnel** (`Hooks.onError`): Logs stack traces, triggers ecosystem hooks, provides structured data
- **User notification** (`ui.notifications.*`): Clean, sanitized messages with full UX control

**Why separation matters:**
1. `Hooks.onError` mutates `error.message` when `msg` is provided (see Foundry GitHub #6669)
2. `clean: true` only works in NotificationOptions, not Hooks.onError
3. User sees only your controlled message, not technical details
4. Explicit control over console logging (`console: false` prevents double-logging)

---

## Quick Reference: Four Error Patterns

| Pattern | Error Funnel | User Notification | Use Case |
|---------|--------------|-------------------|----------|
| **User-facing** | Hooks.onError (`notify: null`) | ui.notifications.error | Unexpected failures |
| **Expected validation** | _(none)_ | ui.notifications.warn | User input errors |
| **Developer-only** | Hooks.onError (`notify: null`) | _(none)_ | Diagnostic logging |
| **High-frequency** | Throttled Hooks.onError | Throttled ui.notifications.warn | Render loops, hooks |

---

## Pattern 1: User-Facing Failures

**Use for:** Unexpected errors, operations that failed, critical failures

```javascript
} catch (err) {
  // Preserve original