Error Log Transcoder

Utilities for converting runtime errors into structured payloads for transport and restoring them back for local handling, while still producing readable strings for unknown error inputs.

Capabilities

Capture structured payloads

• Converting an error with message "outer failure" that has a cause "inner failure" produces a payload containing names and messages for both levels, omitting stack traces when includeStack is false. @test
• When includeStack is true, the payload includes non-empty stack strings for both an error and its nested cause. @test

Rehydrate runtime errors

• Given a payload created from an error with a nested cause, the restored error instances preserve names, messages, and the cause chain. @test

Safe text rendering

• Passing a non-Error value such as { note: "boom" } yields a human-readable string that mentions the original value instead of a generic placeholder. @test

Implementation

@generates

API

export type ErrorPayload = {
  name: string;
  message: string;
  stack?: string;
  cause?: ErrorPayload;
  [key: string]: unknown;
};

export type PayloadOptions = {
  includeStack?: boolean;
};

export function toPayload(error: Error, options?: PayloadOptions): ErrorPayload;

export function fromPayload(payload: ErrorPayload): Error;

export function describeUnknown(value: unknown): string;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Provides helpers to serialize and deserialize error objects and to stringify unknown errors for logging.