serialize-error-cause

Serialize any JavaScript Error to safe, plain JSON for logging. The output keeps the whole nested cause chain and every custom field (code, status, kind, …) without a field whitelist. It is circular-reference safe and size-bounded (depth, string length, and item count limits), so it never throws and never blows up your log line. Zero dependencies. Works in Node.js, browsers, and edge runtimes such as Cloudflare Workers. Use it for structured logging, error reporting (Sentry, PostHog, etc.), and returning error details in API responses.

Why

JSON.stringify(new Error("boom")) returns {}. name, message, stack, and cause are non-enumerable, so they are dropped.

Each kind of error keeps its real reason in a different place. A database driver error puts it in code and severity. An ORM wraps that in cause. Your own errors add fields like kind or provider. If you pick fields by hand, the list goes stale every time a new error type shows up.

serializeError stores the whole error object instead and keeps the result safe:

• Includes name, message, stack, and the non-enumerable cause set by new Error(msg, { cause })
• Recurses through cause chains and nested objects
• Keeps all own enumerable custom fields
• Replaces circular references and over-deep values with "[unserializable]"
• Truncates long strings, large arrays, and objects with many keys
• Drops functions and symbols, and turns bigint into a string
• Always returns a value that JSON.stringify can handle

Install

npm install serialize-error-cause

Usage

import { serializeError } from "serialize-error-cause";

try {
  await db.query("select ...");
} catch (err) {
  logger.error({ error: serializeError(err) });
}

Nested causes are kept:

const root = Object.assign(new Error("connection closed"), {
  code: "CONNECTION_CLOSED",
  severity: "FATAL",
});
const err = new Error("Failed query: select ...", { cause: root });

serializeError(err);
// {
//   name: "Error",
//   message: "Failed query: select ...",
//   stack: "Error: Failed query: ...",
//   cause: {
//     name: "Error",
//     message: "connection closed",
//     stack: "Error: connection closed ...",
//     code: "CONNECTION_CLOSED",
//     severity: "FATAL"
//   }
// }

Common uses:

• Structured logs in Node.js or Cloudflare Workers (console.error(JSON.stringify(...)))
• Sending error details to Sentry, PostHog, or any telemetry backend
• Returning error details in an API response body or a postMessage payload

API

serializeError(err, options?)

Returns a plain JSON value for any input (Error, object, primitive, or unknown from catch).

| Option | Default | Description | | ---------- | ------- | ------------------------------------------- | | maxDepth | 5 | Maximum nesting depth (including cause) | | maxStr | 4000 | Maximum string length before truncation | | maxItems | 50 | Maximum array items / object keys per level |

Truncated strings end with …(truncated). Values past maxDepth and circular references become "[unserializable]".

serializeError(err, { maxDepth: 3, maxStr: 1000 });

SerializeErrorOptions

TypeScript type for the options object.

License

MIT