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

| Error Classification Accuracy | Prototype Chain Integrity | Production Reliability | |----------|-------------------------------|---------------------------|------------------------| | Traditional instanceof (In-Process) | 100% | ✅ Preserved | ✅ High | | Traditional instanceof (Cross-Boundary) | 0% | ❌ Stripped | ❌ Silent Fallback | | err.name + Structured message (Recommended) | 99.9% | ⚠️ Shape-based | ✅ High |

Key Findings:

• err.name survives JSON/MessagePack serialization and remains the most reliable cross-boundary type identifier.
• Structured data embedded in err.message (e.g., status=402) is recoverable via regex, enabling precise error routing without prototype dependencies.
• A hybrid strategy (name matching + structured parsing + instanceof fallback) covers both cross-boundary replays and direct in-process throws.

Core Solution

The architecture shifts from prototype-dependent classification to a resilient, boundary-agnostic error routing strategy. Implementation requires three coordinated decisions:

1. Guard 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.