# Error Handling

> Use when throwing, catching, wrapping, documenting, or testing runtime errors in aa-sdk packages.

- Skill: `alchemyplatform/error-handling` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add alchemyplatform/error-handling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alchemyplatform/error-handling/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alchemyplatform (https://skillmd.com/u/alchemyplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alchemyplatform/error-handling

---


# Error Handling

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

## Rules

| Rule                                      | When to read                                    |
| ----------------------------------------- | ----------------------------------------------- |
| [BaseError](rules/base-error.md)          | Before adding package runtime errors.           |
| [No plain Error](rules/no-plain-error.md) | Before writing throw statements in `packages/`. |
| [Raise footgun](rules/raise-footgun.md)   | Before using or modifying `raise`.              |

## Evidence

- `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`.