or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-classes.mdindex.mdserialization.md
tile.json

tessl/npm-backstage--errors

Common utilities for error handling within Backstage with structured error classes and serialization functions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@backstage/errors@1.2.x

To install, run

npx @tessl/cli install tessl/npm-backstage--errors@1.2.0

index.mddocs/

Backstage Errors

Backstage Errors provides essential error handling utilities for the Backstage developer platform, offering a comprehensive set of structured error classes and serialization functions that enable consistent error management across frontend and backend components.

Package Information

  • Package Name: @backstage/errors
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @backstage/errors

Core Imports

import { 
  // Error classes
  CustomErrorBase, 
  InputError, 
  AuthenticationError,
  NotAllowedError,
  NotFoundError,
  ConflictError,
  NotModifiedError,
  NotImplementedError,
  ServiceUnavailableError,
  ForwardedError,
  ResponseError,
  // Serialization functions
  serializeError,
  deserializeError,
  stringifyError,
  parseErrorResponseBody,
  // Validation functions
  isError,
  assertError,
  // Types
  type ErrorLike,
  type SerializedError,
  type ErrorResponseBody,
  type ConsumedResponse
} from "@backstage/errors";

For CommonJS:

const { 
  // Error classes
  CustomErrorBase, 
  InputError, 
  AuthenticationError,
  NotAllowedError,
  NotFoundError,
  ConflictError,
  NotModifiedError,
  NotImplementedError,
  ServiceUnavailableError,
  ForwardedError,
  ResponseError,
  // Serialization functions
  serializeError,
  deserializeError,
  stringifyError,
  parseErrorResponseBody,
  // Validation functions
  isError,
  assertError
} = require("@backstage/errors");

Basic Usage

import { 
  NotFoundError, 
  serializeError, 
  deserializeError, 
  isError 
} from "@backstage/errors";

// Create structured errors with cause chaining
const userNotFound = new NotFoundError(
  "User with ID 'user123' not found",
  originalError
);

// Serialize errors for logging or network transmission
const serialized = serializeError(userNotFound, { includeStack: true });
console.log(JSON.stringify(serialized, null, 2));

// Deserialize errors from JSON
const restored = deserializeError(serialized);

// Validate error-like objects
if (isError(someUnknownValue)) {
  console.log(`Error: ${someUnknownValue.name} - ${someUnknownValue.message}`);
}

Architecture

Backstage Errors is organized around several key components:

  • Error Classes: Structured error types with HTTP status code mapping and cause chaining
  • Base Classes: CustomErrorBase for creating domain-specific error types
  • Response Handling: ResponseError for failed HTTP requests with parsed error bodies
  • Serialization: JSON-safe error serialization and deserialization for network transmission
  • Type Safety: Error validation and assertion utilities with TypeScript support

Capabilities

Error Classes

Structured error classes that map to common HTTP status codes and business logic scenarios. Each error extends CustomErrorBase and supports cause chaining for debugging.

class CustomErrorBase extends Error {
  readonly cause?: Error | undefined;
  constructor(message?: string, cause?: Error | unknown);
}

class InputError extends CustomErrorBase {
  name: 'InputError';
}

class AuthenticationError extends CustomErrorBase {
  name: 'AuthenticationError';
}

class NotAllowedError extends CustomErrorBase {
  name: 'NotAllowedError';
}

class NotFoundError extends CustomErrorBase {
  name: 'NotFoundError';
}

class ConflictError extends CustomErrorBase {
  name: 'ConflictError';
}

Error Classes

Error Serialization

Utilities for converting errors to JSON-safe format and back, enabling error transmission over networks and consistent logging formats.

function serializeError(
  error: Error,
  options?: { includeStack?: boolean }
): SerializedError;

function deserializeError<T extends Error = Error>(
  data: SerializedError
): T;

function stringifyError(error: unknown): string;

type SerializedError = {
  name: string;
  message: string;
  stack?: string;
  code?: string;
};

Serialization

Error Validation

Type guards and assertion functions for runtime error validation and type safety.

function isError(value: unknown): value is ErrorLike;
function assertError(value: unknown): asserts value is ErrorLike;

type ErrorLike = {
  name: string;
  message: string;
  stack?: string;
  [unknownKeys: string]: unknown;
};

HTTP Response Errors

Specialized error handling for failed HTTP requests with automatic error body parsing.

class ResponseError extends Error {
  readonly response: ConsumedResponse;
  readonly body: ErrorResponseBody;
  readonly cause: Error;
  readonly statusCode: number;
  readonly statusText: string;
  
  static fromResponse(
    response: ConsumedResponse & { text(): Promise<string> }
  ): Promise<ResponseError>;
}

type ErrorResponseBody = {
  error: SerializedError;
  request?: {
    method: string;
    url: string;
  };
  response: {
    statusCode: number;
  };
};

Types

type ConsumedResponse = {
  readonly headers: {
    append(name: string, value: string): void;
    delete(name: string): void;
    get(name: string): string | null;
    has(name: string): boolean;
    set(name: string, value: string): void;
    forEach(callback: (value: string, name: string) => void): void;
    entries(): IterableIterator<[string, string]>;
    keys(): IterableIterator<string>;
    values(): IterableIterator<string>;
    [Symbol.iterator](): Iterator<[string, string]>;
  };
  readonly ok: boolean;
  readonly redirected: boolean;
  readonly status: number;
  readonly statusText: string;
  readonly type: ResponseType;
  readonly url: string;
};