Inngest's instanceof lies: why custom error classes vanish across step.run

uard against non-Error objects** to prevent runtime crashes when unknown payloads cross boundaries. 2. Match on err.name as the primary classifier, since it survives serialization. 3. Extract structured data from err.message using regex or parsing, ensuring machine-readable context travels with the error. 4. Retain instanceof as a fallback for direct throws that never cross a serialization boundary.

export class TTSUpstreamError extends Error {
  constructor(public status: number, message: string) {
    super(message);
    this.name = "TTSUpstreamError";
  }
}
And the failure handler did the obvious thing:

function ttsReasonFor(err: unknown): string {
  if (err instanceof TTSUpstreamError) return `elevenlabs_upstream:${err.status}`;
  if (err instanceof TTSNotConfiguredError) return "elevenlabs_not_configured";
  return "elevenlabs_unknown";
}

function ttsReasonFor(err: unknown): string {
  if (!(err instanceof Error)) return "elevenlabs_unknown";
  const name = err.name;
  const msg = err.message ?? "";
  if (name === "TTSNotConfiguredError") return "elevenlabs_not_configured";
  if (name === "TTSUpstreamError") {
    const status = msg.match(/status=(\d{3})/)?.[1] ?? "0";
    return `elevenlabs_upstream:${status}`;
  }
  // Direct throws (outside step.run) keep class identity intact.
  if (err instanceof TTSUpstreamError) return `elevenlabs_upstream:${err.status}`;
  if (err instanceof TTSNotConfiguredError) return "elevenlabs_not_configured";
  return "elevenlabs_unknown";
}

Architecture Decisions:

• Structured Error Construction: Errors must be instantiated with machine-readable payloads in the message: new TTSUpstreamError(402, "ElevenLabs failed (status=402)").
• Boundary-Agnostic Routing: The classifier treats cross-boundary replays and direct throws identically, prioritizing deterministic parsing over prototype checks.
• Defensive Fallbacks: instanceof remains in the codebase but is explicitly scoped to in-process scenarios, preventing accidental reliance on fragile prototype chains.

Pitfall Guide

1. Prototype Chain Assumption: Assuming instanceof works across async boundaries, memoization layers, or serialization boundaries. Prototype identity is strictly in-process and vanishes upon JSON/MessagePack serialization.
2. Unstructured Error Messages: Failing to embed machine-readable data in err.message or custom fields. Without structured payloads, cross-boundary errors become opaque strings that cannot be programmatically routed.
3. Missing Type Guards: Accessing .name or .message on unknown payloads without verifying err instanceof Error. This causes TypeError crashes in catch blocks when non-Error objects (e.g., strings, primitives) are thrown.
4. Overlooking Cross-Boundary Contexts: Applying in-process error handling patterns to Web Workers (postMessage), RPC frameworks, or JSON-logging pipelines. All these systems strip prototypes identically to Inngest's step boundaries.
5. Relying on error.stack: Assuming stack traces survive serialization. Many runtimes and serialization layers truncate or omit stack for performance/security, making it an unreliable classifier.
6. Dropping Fallback Logic: Removing instanceof checks entirely after adopting name matching. Direct throws outside step boundaries retain prototype identity, and instanceof remains the cleaner, more performant check for those specific paths.

Deliverables

• 📘 Error Boundary Serialization Blueprint: Architecture guide detailing how to design custom error classes for distributed/step-based systems, including constructor patterns, serialization-safe field mapping, and catch-block routing templates.
• ✅ Cross-Boundary Error Handling Checklist: Pre-flight validation list covering type guards, structured message formatting, name vs instanceof scoping, and serialization boundary identification (Inngest, Workers, RPC, logging).
• ⚙️ Configuration Templates: Ready-to-use TypeScript/JavaScript snippets for standardized error constructors, regex-based message parsers, and hybrid classifier functions that can be dropped into existing pipelines without refactoring core business logic.