Pipeline Error Handling

Design a small error module that standardizes how domain-specific errors capture and surface their causes. The module should make it easy to produce meaningful error messages that automatically mention upstream failures while keeping error names aligned with their subclasses. Keep the API surface compact and centered on wrapping errors rather than general logging or formatting utilities.

Capabilities

Cause-aware base error

• Creating the base error with message "upload failed" and a cause Error("disk full") produces a message containing both snippets in order ("upload failed" then "disk full") and exposes the original Error as the cause property. @test
• Passing a non-Error cause value (e.g., the string "oops") still appends that value to the message but leaves the cause property undefined. @test

Named subclasses

• Subclasses for configuration and task failures inherit the base behavior and their name matches the subclass name without extra work from the caller. @test
• A subclass instance created without a cause keeps the original message unchanged and has no cause value. @test

Unknown-to-error guard

• A helper that accepts unknown input returns it unchanged when it is already an Error, otherwise produces a new Error whose message includes either the provided string (e.g., "boom") or a fallback label like "Unexpected failure" when the value is nullish; the fallback message must not be empty. @test

Implementation

@generates

API

export interface CauseOptions {
  cause?: unknown;
}

export class PipelineError extends Error {
  constructor(message: string, options?: CauseOptions);
  cause?: Error;
}

export class InvalidConfigError extends PipelineError {}
export class TaskFailedError extends PipelineError {}

export function ensureError(value: unknown, fallbackMessage?: string): Error;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Provides a cause-aware base error utility and helpers for validating error-like values.