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

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

notify: null

notify: null

Pattern 1: User-Facing Failures

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

} catch (err) {
  // Preserve original error as cause when wrapping non-Errors
  const error = err instanceof Error ? err : new Error(String(err), { cause: err });

  // Error funnel: stack traces + ecosystem hooks (no UI)
  Hooks.onError(`YourModule.${contextDescription}`, error, {
    msg: "[YourModule]",
    log: "error",
    notify: null,  // No UI from hook
    data: { contextDescription, userFacingDescription }  // Structured context
  });

  // Fully controlled user message (sanitized, no console - already logged)
  ui.notifications.error(`[YourModule] ${userFacingDescription}`, {
    clean: true,
    console: false  // Hooks.onError already logged
  });
}

Key points:

• User sees only

  userFacingDescription

  (no technical details leaked)
• Stack trace logged via Hooks.onError (full Error object)
• Ecosystem visibility (other modules can listen to

  Hooks.on("error", ...)

  )
• Structured

  data

  for debugging and hook subscribers
• Explicit

  console: false

  prevents double-logging

Pattern 2: Expected Validation / Recoverable Issues

Use for: User input errors, missing data, expected validation failures

} catch (err) {
  const message = `[YourModule] ${userFacingDescription}`;
  ui.notifications.warn(message, {
    clean: true,
    console: false  // Expected failures - no console noise
  });
}

Key points:

• Uses

  warn

  severity (not

  error

  ) for expected cases
• Simpler than Hooks.onError (no error funnel needed for routine validation)

• console: false

  avoids noise for common user-driven failures
• Optional: Gate console logging behind debug flag:

  console: game.settings.get("your-module", "enableProfiling")
  

Pattern 3: Developer-Only Errors

Use for: Diagnostic logging, internal errors that don't need user notification

} catch (err) {
  const error = err instanceof Error ? err : new Error(String(err), { cause: err });
  Hooks.onError(`YourModule.${contextDescription}`, error, {
    msg: "[YourModule]",
    log: "error",
    notify: null,  // Log only, no UI spam
    data: { contextDescription }  // Structured context for debugging
  });
}

Key points:

• Uses error funnel (consistency) but no notification
• Stack traces logged for developers
• No UI spam for internal diagnostics
• Alternative: Use

  console.error(...)

  for truly isolated cases (but lose ecosystem hooks)

Pattern 4: High-Frequency Errors

Use for: Render loops, hooks, event handlers that might error repeatedly

// Module-scoped throttle (outside class/function)
const errorThrottles = new Map();

// In catch block:
} catch (err) {
  const throttleKey = contextDescription;
  const lastError = errorThrottles.get(throttleKey) || 0;

  // Throttle: 5 second window per context
  if (Date.now() - lastError > 5000) {
    const error = err instanceof Error ? err : new Error(String(err), { cause: err });

    // Error funnel (no UI)
    Hooks.onError(`YourModule.${contextDescription}`, error, {
      msg: "[YourModule]",
      log: "warn",
      notify: null,  // No UI from hook
      data: { contextDescription, userFacingDescription }
    });

    // Separate controlled notification (console: false prevents double-logging)
    ui.notifications.warn(`[YourModule] ${userFacingDescription}`, {
      clean: true,
      console: false  // Already logged via Hooks.onError
    });

    errorThrottles.set(throttleKey, Date.now());
  }
}

Key points:

• Throttles to prevent notification queue flood
• Module-scoped Map prevents spam across multiple instances
• Uses

  warn

  severity for non-critical repeated errors
• Separates error funnel (logs only) from user notification
• Explicit

  console: false

  prevents double-logging

Decision Tree: Classifying Errors

Ask these questions:

1. Is this unexpected? (system failure, unhandled case, critical error) → Pattern 1: User-facing failures

2. Is this expected validation? (user input error, missing required data) → Pattern 2: Expected validation

3. Is this diagnostic-only? (internal state, no user impact) → Pattern 3: Developer-only

4. Could this fire repeatedly? (render loop, hook, event handler) → Pattern 4: High-frequency throttled

Foundry-Specific Gotchas

1.

Hooks.onError

Mutates Error Objects

Critical:

Hooks.onError

error.message

msg

// Internal Foundry implementation (from GitHub #6669):
if (msg) err.message = `${msg}: ${err.message}`;

This is why we separate funnel from notification:

• Error funnel gets the Error object (stack traces preserved)
• User notification uses clean string (no mutation affects UX)

Always normalize to Error objects:

const error = err instanceof Error ? err : new Error(String(err), { cause: err });

2.

console

Default Behavior Not Documented

Issue: Foundry V13 docs don't explicitly state the default value for

NotificationOptions.console

Evidence: API examples show

{ console: false }

true

Best practice: Be explicit to prevent double-logging and future-proof against default changes:

ui.notifications.error(message, {
  clean: true,
  console: false  // Explicit is better than implicit
});

3.

notify

String Values Are Undocumented

Issue:

Hooks.onError

notify: null | string

Your assumption:

notify

"error"

"warn"

"info"

ui.notifications.*

Reality: Likely correct but NOT explicitly documented.

Best practice: Use

notify: null

ui.notifications.*

// Avoid relying on undocumented notify strings
Hooks.onError(..., { notify: null });  // Error funnel only
ui.notifications.error(...);           // Separate notification

4.

clean: true

Only Works in NotificationOptions

Issue:

{ clean: true }

ui.notifications.*

Does NOT work in

Hooks.onError

msg

Best practice:

• Keep

  msg

  in Hooks.onError generic (module prefix only):

  msg: "[YourModule]"

• Put user/document data in separate

  ui.notifications.*

  call with

  { clean: true }

// ❌ Bad - untrusted data in Hooks.onError msg
Hooks.onError(..., { msg: `[Module] ${userInput}` });  // Not sanitized!

// ✅ Good - untrusted data in ui.notifications with clean: true
Hooks.onError(..., { msg: "[Module]", notify: null });
ui.notifications.error(`[Module] ${userInput}`, { clean: true });

5.

{ cause: err }

Has Excellent Support

Good news: Error

cause

• Available since September 2021 (4+ years)
• Foundry V13 minimum: Chromium 122, Firefox 127, Electron 33+
• Safe to use in all Foundry V13+ environments

Usage:

const error = err instanceof Error ? err : new Error(String(err), { cause: err });

Preserves original error context for debugging in modern browsers.

Implementation Checklist

When adding error handling to your module:

1. Audit All Catch Blocks

grep -r "} catch" scripts/

2. Classify Each Error

• Unexpected failure? → Pattern 1 (user-facing)
• Expected validation? → Pattern 2 (expected validation)
• Diagnostic only? → Pattern 3 (developer-only)
• High-frequency? → Pattern 4 (throttled)

3. Replace Patterns

• console.log

  →

  console.error

  or Hooks.onError (minimum fix)
• Manual notification + console → Hooks.onError (

  notify: null

  ) + ui.notifications.*
• Expected failures →

  ui.notifications.warn

  with

  console: false

• Use

  { clean: true }

  on ui.notifications.* for user/document data
• Default to

  console: false

  (prevents noise + double-logging)
• Never put untrusted strings in Hooks.onError

  msg

  (it's a prefix only)
• Always separate error funnel from user notification
• Preserve original error:

  new Error(String(err), { cause: err })

• Add structured

  data

  to Hooks.onError for debugging
• Throttle errors in render loops/hooks (prevent UI spam)

4. Test Error Paths

• Verify user-facing errors show clean message (no technical details leaked)
• Verify stack traces in console (Error objects via Hooks.onError)
• Verify

  warn

  severity used for expected validation errors
• Check that diagnostic errors don't spam UI (Hooks.onError with

  notify: null

  )
• Test throttling for high-frequency error paths (5 second window)
• Verify no double-logging (Hooks.onError + ui.notifications with

  console: false

  )
• Verify structured

  data

  appears in error hooks for debugging

Verification Notes

Verified against Foundry V13 API (2025-12-31):

✅ Documented and Correct

• NotificationOptions.console

  : Optional boolean - "Whether to log the message to the console"

• NotificationOptions.clean

  : Optional boolean - "Whether to clean the provided message string as untrusted user input"

• Hooks.onError

  signature:

  static onError(
    location: string,
    error: Error,
    options?: {
      data?: object;
      log?: null | string;
      msg?: string;
      notify?: null | string;
    }
  ): void
  

• All four parameters documented:

  • msg

    : String - "A message which should prefix the resulting error or notification"

  • log

    : null | string - "The level at which to log the error to console (if at all)"

  • notify

    : null | string - "The level at which to spawn a notification in the UI (if at all)"

  • data

    : object - "Additional data to pass to the hook subscribers"
• Notification types:

  "info"

  ,

  "warn"

  ,

  "error"

  (all documented)

• notify: null

  : Explicitly documented as valid (suppresses UI notification)

• { cause: err }

  : Excellent browser support (ES2022, 4+ years available)

⚠️ Undocumented Behaviors

• console

  default value not explicitly stated (defensive

  console: false

  recommended)

• notify

  string values not enumerated (use

  notify: null

  + separate notifications)

• Hooks.onError

  mutates

  error.message

  (normalize to Error objects, separate funnel from notification)

Benefits of This Approach

• Foundry-native: Uses only documented NotificationOptions and Hooks.onError APIs
• Full UX control: Always separates error funnel from user message (no technical leaks)
• Stack traces: Error objects via Hooks.onError include full stack traces in console
• Preserves context:

  { cause: err }

  retains original error when wrapping non-Errors
• Structured debugging:

  data

  parameter provides context to hook subscribers and debugging
• Ecosystem-compatible: Error funnel allows other modules to listen to your errors
• Better UX: Severity discipline (warn vs error) + throttling prevents notification spam
• Sanitization:

  { clean: true }

  on ui.notifications.* prevents XSS from error messages
• No double-logging: Explicit

  console: false

  prevents duplicate entries
• Reduced console noise: Expected validation errors don't clutter console by default
• Consistent pattern: All errors use same "funnel + notification" approach
• Robust throttling: Module-scoped Map prevents spam across multiple instances
• Future-proof: Uses only documented Foundry V13 error handling mechanisms

Optional Enhancement: Localization

For published modules, consider localizing error messages:

const message = game.i18n.format("YOUR_MODULE.Error.FailedToAddItem", {
  error: err.message
});
ui.notifications.error(message, { clean: true, console: false });

Note: If using

game.i18n.format

format

clean: true

References

Foundry V13 API Documentation

• NotificationOptions Interface
• Hooks.onError Method
• Notifications Class

GitHub Issues

• Hooks.onError Implementation #6669 - Documents error.message mutation behavior

Browser APIs

• Error.cause - MDN
• Can I Use: Error.cause

Related Skills

• foundry-vtt-performance-safe-updates

  - Multi-client update safety patterns

• foundry-vtt-dialog-compat

  - DialogV2 Shadow DOM patterns

• foundry-vtt-version-compat

  - API compatibility layer patterns

Example: Real-World Usage

// In blades-alternate-actor-sheet.js
import { queueUpdate } from "./lib/update-queue.js";

async _onItemCreate(event) {
  event.preventDefault();
  const itemType = event.currentTarget.dataset.itemType;

  try {
    // Attempt to create item
    const itemData = {
      name: `New ${itemType}`,
      type: itemType,
      system: {}
    };

    await queueUpdate(async () => {
      await this.actor.createEmbeddedDocuments("Item", [itemData]);
    });

    ui.notifications.info(`[BitD-Alt] Created new ${itemType}`);

  } catch (err) {
    // Pattern 1: User-facing failure
    const error = err instanceof Error ? err : new Error(String(err), { cause: err });

    Hooks.onError("BitD-Alt.ItemCreate", error, {
      msg: "[BitD-Alt]",
      log: "error",
      notify: null,
      data: { itemType, actorId: this.actor.id }
    });

    ui.notifications.error(`[BitD-Alt] Failed to create ${itemType}`, {
      clean: true,
      console: false
    });
  }
}

Last Updated: 2025-12-31 Status: Production-Ready (Verified against Foundry V13 API) Maintainer: Claude Code (BitD Alternate Sheets)