errors

Errors

Each package owns its errors in its own src/errors.ts, as plain native classes. There is no shared errors lib: the former @ledgerhq/errors package has been removed.

Define errors

A package groups its errors in src/errors.ts. Extend Error directly and set a stable name. The name string is the contract — keep it stable, it is what survives across process/serialization boundaries.

// message-only
export class FooNotFound extends Error {
  override name = "FooNotFound";
}

// with a default message
export class InvalidChallenge extends Error {
  override name = "InvalidChallenge";
  constructor() {
    super("backend returned an invalid challenge");
  }
}

// with extra fields
export class HttpError extends Error {
  override name = "HttpError";
  readonly status: number | undefined;
  constructor(message: string, status?: number) {
    super(message);
    this.status = status;
  }
}

Group a family under a per-package base class so callers can catch the whole set:

export class WalletAuthError extends Error {
  override name = "WalletAuthError";
}
export class WalletAuthSignatureError extends WalletAuthError {
  override name = "WalletAuthSignatureError";
  constructor(cause: unknown) {
    super("failed to sign challenge", { cause });
  }
}

See libs/ledger-auth/src/errors.ts for a full reference.

cause

Use the native second argument: super(message, { cause }). Error cause was standardized in ES2022 and is supported by modern runtimes; its TypeScript typing (ErrorOptions) requires lib: es2022.error (i.e. es2022). Coin modules and some older packages still target es2020 — there, declare and assign manually:

export class BroadcastError extends Error {
  override name = "BroadcastError";
  cause?: unknown;
  constructor(message: string, cause?: unknown) {
    super(message);
    this.cause = cause;
  }
}

Check error type: prefer error.name

Prefer error.name === "FooNotFound" over instanceof FooNotFound.