error-tracing

Error Tracing

Read stack traces and error chains to trace errors back to their root cause across synchronous, asynchronous, and distributed code paths.

When to Use

• An error or stack trace appears in console, logs, or test output
• The user shares an exception and needs help understanding it
• Debugging async errors with incomplete stack traces
• Setting up error boundaries in React or similar frameworks
• Mapping minified production errors back to source code

Core Patterns

Reading Stack Traces

Stack traces read from top to bottom. The top frame is where the error was thrown; the bottom frame is the entry point:

Error: Cannot read properties of undefined (reading 'email')
    at formatUser (src/utils/format.ts:42:18)        <-- ERROR THROWN HERE
    at processUsers (src/services/user.ts:87:12)      <-- Called formatUser
    at handler (src/routes/users.ts:23:5)             <-- Called processUsers
    at Layer.handle (node_modules/express/lib/router/layer.js:95:5)

Reading strategy:

1. Read the error message first — it often tells you exactly what is wrong
2. Find the first frame in YOUR code (skip node_modules)
3. Go to that file and line — src/utils/format.ts:42
4. Understand what variable is undefined and trace where it came from
5. Walk up the stack to find where the bad data originated

// The error says: Cannot read 'email' of undefined
// At format.ts:42: user.email  — so `user` is undefined
// At user.ts:87: formatUser(users[i])  — so users[i] is undefined
// Root cause: array has gaps or index is out of bounds

Error Chains (Cause Property)

Wrap errors to add context while preserving the original cause:

// Build error chains with the cause option (ES2022)
async function createOrder(data: OrderInput): Promise<Order> {
  let user: User;
  try {
    user = await fetchUser(data.userId);
  } catch (error) {
    throw new Error(`Failed to create order: user lookup failed`, {
      cause: error,
    });
  }

  try {
    return await insertOrder(user, data);
  } catch (error) {
    throw new Error(`Failed to create order: database insert failed`, {
      cause: error,
    });
  }
}

// Reading the error chain
function logErrorChain(error: Error): void {
  let current: Error | undefined = error;
  let depth = 0;
  while (current) {
    const indent = "  ".repeat(depth);
    console.error(`${indent}${current.message}`);
    if (current.stack) {
      console.error(`${indent}${current.stack.split("\n")[1]?.trim()}`);
    }
    current = current.cause instanceof Error ? current.cause : undefined;
    depth++;
  }
}

// Output:
// Failed to create order: database insert failed
//   at createOrder (src/services/order.ts:18:11)
//   ECONNREFUSED 127.0.0.1:5432
//     at Connection.connect (node_modules/pg/lib/connection.js:45:9)