Error Serialization Toggle

Create a utility that serializes thrown values into plain objects while allowing callers to opt in to sharing stack traces.

Capabilities

Default serialization omits stacks

• Serializing a thrown value with no options returns its name and message without any stack trace included. @test

Debug mode includes stacks

• When a caller explicitly opts in, the serialized result contains the stack trace of the original error. @test

Cause chains respect the toggle

• When an error has a nested cause, the serialized cause is included, and stack traces for both levels only appear when the opt-in flag is set. @test

Implementation

@generates

API

export type SerializedAppError = {
  name: string;
  message: string;
  stack?: string;
  cause?: SerializedAppError;
};

/**
 * Converts any thrown value into a serializable structure.
 * When includeStack is true, stack traces for the error and any nested causes are attached.
 */
export function serializeAppError(
  error: unknown,
  options?: { includeStack?: boolean }
): SerializedAppError;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Provides structured error utilities and optional stack trace serialization.