Upstream Error Forwarding

A utility for wrapping upstream failures with local context while surfacing the original error type.

Capabilities

Contextual wrapping keeps upstream type

• Given an upstream error named "ValidationError" with message "payload missing", calling wrapUpstreamError("sync catalog", cause) returns an error whose name remains "ValidationError" and whose message contains both "sync catalog" and "payload missing". @test

Cause remains attached

• The wrapped error exposes the original Error instance as its cause, preserving identity for debugging and logging. @test

Graceful handling of non-error causes

• When the cause is not an Error (for example, a string "timeout"), the wrapper uses name value "Error" and the message still includes the provided context plus the stringified cause. @test

Implementation

@generates

API

/**
 * Wraps an upstream failure with local context while keeping the upstream type visible.
 */
export function wrapUpstreamError(step: string, cause: unknown): Error;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Utilities for wrapping underlying causes with contextual messages while surfacing upstream error types.

@satisfied-by