Wrapped Error Toolkit

Utilities that wrap upstream failures with consistent messages, filter causes to real errors, and allow transport-safe serialization.

Capabilities

Contextual wrapping

• Creating a gateway error with message "Gateway timeout" and cause new Error("db offline") yields an error whose message becomes Gateway timeout: db offline while retaining the provided error as its cause. @test
• Supplying a non-error cause (e.g., string "oops") results in an error whose message becomes Gateway timeout: oops but whose cause property is unset. @test

Forwarding upstream failures

• Forwarding an upstream error named "ThirdPartyError" with message "service down" using the context "catalog request failed" produces an error whose name remains "ThirdPartyError", whose message becomes catalog request failed: service down, and whose cause remains the original upstream error. @test
• Forwarding without an error-like input (e.g., passing 42) throws an informative exception mentioning the received value. @test

Serialization roundtrip

• Serializing an error with a nested cause returns a JSON-friendly object containing name, message, and nested cause fields but omitting stacks by default. @test
• When serialization is requested with stack inclusion, both the error and its nested cause include non-empty stack fields in the serialized object. @test
• Deserializing the serialized object reconstructs an Error whose name, message, and nested cause match the original structure. @test

Implementation

@generates

API

export interface SerializedErrorPayload {
  name: string;
  message: string;
  stack?: string;
  cause?: SerializedErrorPayload;
}

export function createServiceError(message: string, cause?: unknown): Error;

export function forwardUpstreamError(context: string, upstream: unknown): Error;

export function serializeForTransport(error: unknown, includeStack?: boolean): SerializedErrorPayload;

export function deserializeFromTransport(payload: SerializedErrorPayload): Error;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Error utilities for wrapping, forwarding, and serializing errors. @satisfied-by