name	error-handling
description	Use when throwing, catching, wrapping, documenting, or testing runtime errors in aa-sdk packages.
last_verified	2026-05-06T00:00:00.000Z

Error Handling

Runtime package errors should use the SDK error hierarchy rooted at @alchemy/common BaseError.

Rule	When to read
BaseError	Before adding package runtime errors.
No plain Error	Before writing throw statements in `packages/`.
Raise footgun	Before using or modifying `raise`.

packages/common/src/errors/BaseError.ts extends viem's BaseError.
.eslintrc forbids throw new Error(...) in packages/**/* except tests.
.eslintrc forbids import { BaseError } from "viem" to prevent accidentally using viem's BaseError instead of @alchemy/common's.
packages/wallet-apis/src/utils/schema.ts wraps Zod validation failures in @alchemy/common BaseError.

name	error-handling
description	Use when throwing, catching, wrapping, documenting, or testing runtime errors in aa-sdk packages.
last_verified	2026-05-06T00:00:00.000Z

Runtime package errors should use the SDK error hierarchy rooted at @alchemy/common BaseError.

Rule	When to read
BaseError	Before adding package runtime errors.
No plain Error	Before writing throw statements in `packages/`.
Raise footgun	Before using or modifying `raise`.

packages/common/src/errors/BaseError.ts extends viem's BaseError.
.eslintrc forbids throw new Error(...) in packages/**/* except tests.
.eslintrc forbids import { BaseError } from "viem" to prevent accidentally using viem's BaseError instead of @alchemy/common's.
packages/wallet-apis/src/utils/schema.ts wraps Zod validation failures in @alchemy/common BaseError.

error-handling