add-exception
/add-exception
How to add a new Kavo exception — hierarchy placement, error-code catalog entry, problem-details wiring, and adapter error mapping. Use when a change needs to signal a new failure mode to callers rather than reusing an existing exception.
- Author
- kavo-labs ↗
- Repository
- kavo ↗
- Licence
- MIT
- Last repository change
- 17.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
How to add a new Kavo exception — hierarchy placement, error-code catalog entry, problem-details wiring, and adapter error mapping. Use when a change needs to signal a new failure mode to callers rather than reusing an existing exception.
Original author description
How to add a new Kavo exception — hierarchy placement, error-code catalog entry, problem-details wiring, and adapter error mapping. Use when a change needs to signal a new failure mode to callers rather than reusing an existing exception.
How it works
- Decide it's actually new
- Where it goes
- What you don't touch
- Tests
- Docs
SKILL.md preview
---
name: add-exception
description: How to add a new Kavo exception — hierarchy placement, error-code catalog entry, problem-details wiring, and adapter error mapping. Use when a change needs to signal a new failure mode to callers rather than reusing an existing exception.
---
# Adding an exception
Kavo has one exception hierarchy, one error-code catalog, and one wire shape
(RFC 9457 problem details, ADR-0009) — `docs/internals/architecture/06-error-handling.md`.
A new failure mode is a new catalog entry, never a raw `Error`, a bare string
code, or a second serialization path.
## Decide it's actually new
Check `ERROR_CATALOG` (`packages/core/src/errors/error-catalog.ts`) and the
hierarchy first — a new failure mode for an _existing_ code (e.g. another
reason a request is malformed) is usually a `QueryValidationException` issue,
not a new class. Only add a leaf when the failure needs its own HTTP status,
its own payload shape, or callers need to `instanceof`/catch it distinctly.
## Where it goes
1. **The class** — a new leaf under `KavoException`
(`packages/core/src/errors/`), named `*Exception`. It implements the
`KavoExceptionShape` contract; downstream layers (including `@kavo/nest`'s
filter and `@kavo/next`'s `toErrorResponse`) program against that shape,
never the concrete class, so don't
add fields the base contract can't express without extending the contract
itself.
2. **The catalog entry** — `ERROR_CATALOG` gets one row: a stable
`KAVO_SNAKE_CASE` code, HTTP status, title, and an English message
template with `{param}` placeholders. **Codes are public API surface** —
once shipped, renaming one is a breaking change.
Pick the name you're willing to keep.
3. **Payload extensions, if any** — follow the existing pattern rather than
inventing a shape: issue-level detail lives in `errors[]` (query
validation), per-item detail in `items[]` (bulk), a typed flag alongside
the message (`retryable` on `TransactionException`). A new top-level wire
field needs a reason `errors[]`/`items[]` can't already carry it.
4. **`ErrorContext`** — the throw site doesn't need to fill
`entityName`/`operation`/`correlationId` itself; `DefaultErrorHandler`
backfills whatever's missing. Don't hand-roll that at the throw site.
5. **Adapter mapping, if it originates from `@kavo/typeorm`** — add the
translation in the adapter's own table (`mapDriverError`, doc 09 §5)
_inside the adapter package_. Core never gains ORM-specific knowledge to
recognize a driver error; whatever the adapter doesn't recognize already
falls through to `PersistenceException` with the original as `cause`.
6. **`exposeInternals`** — if the new exception can carry adapter/driver
detail, gate it behind `errors.exposeInternals` (default `false`) the same
way `PersistenceException.cause` is gated — never leak it unconditionally.
## What you don't touch
`toProblemDetails`, the `@kavo/nest` filter, and `@kavo/next`'s
`toErrorResponse` are all generic over the `KavoExceptionShape` contract — a
new leaf needs no changes in any of them. If adding your exception seems to
require touching one of these, the new class is missing something the
contract already provides; fix the class, not the generic machinery.
## Tests
Per the `write-tests` skill: assert the thrown exception's **type and its
`KAVO_SNAKE_CASE` code** (not just the message — the code is the public
contract), the resulting HTTP status and problem-details shape end-to-end for
anything reachable over HTTP, and — for adapter-originated errors — that the
mapping table actually recognizes the driver error it claims to.
## Docs
Add the row to the error-catalog table in
`docs/internals/architecture/06-error-handling.md` §2. A code missing from
that table is invisible to the next reader and to API consumers relying on
the docs as the catalog's source of truth.
Versions
The database has no other skills named add-exception.
Database snapshot: 13.11.2026 · package version 1dfbb5a8b0d7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100error-handling
Reference for Kavo's exception hierarchy, KAVO_* error-code catalog, and the RFC 9457 problem-details wire shape every generated route returns on failure. Use when handling/mapping a Kavo error, deciding which exception to throw from a custom handler/@Override, or answering… - 100problem-details-rfc9457
Use when generating error responses, exception listeners, or custom exceptions in a Symfony API. Defines RFC 9457 (problem+json) error format, mapping domain exceptions to HTTP status codes, and a single kernel exception listener. Use when the task mentions error handling,… - 100problem-details-rfc9457
Use when implementing exception mapping or RFC 9457 error responses in Spring Boot 3. Preserve an existing legacy error contract unless migration is requested. - 100abp-exception-handling
ABP Framework v10.x (10.4–10.6) exception handling: BusinessException, UserFriendlyException, RemoteServiceErrorResponse, HTTP status mapping, error code localization. Use for error handling in ABP, when you need a business exception or an HTTP error response. - 100abp-exception-handling
ABP Framework v10.x (10.4–10.6) exception handling: BusinessException, UserFriendlyException, RemoteServiceErrorResponse, HTTP status mapping, error code localization. Use for error handling in ABP, when you need a business exception or an HTTP error response. - 100nextjs-integration
How to wire @kavo/next into an app's Next.js App Router — createKavoHandler, entity wiring, custom operations, and OpenAPI export. Use when a user is integrating Kavo into their own Next.js app, not when changing @kavo/next's own source (see…