handling-errors
/handling-errors
Rules for errors - Result vs throw, retries, the ERRORS catalog, hints, exit codes, boundary catches, one shape over HTTP, CLI and MCP. Use when you add or change an error code, hint, exit code or catch, or review such a diff. Don't use for an operation's error list (use working-with-contracts).
- Author
- AnDeVerin ↗
- Repository
- spur-board ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.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
Rules for errors - Result vs throw, retries, the ERRORS catalog, hints, exit codes, boundary catches, one shape over HTTP, CLI and MCP. Use when you add or change an error code, hint, exit code or catch, or review such a diff. Don't use for an operation's error list (use working-with-contracts).
Triggers from the description
Original author description
Rules for errors - Result vs throw, retries, the ERRORS catalog, hints, exit codes, boundary catches, one shape over HTTP, CLI and MCP. Use when you add or change an error code, hint, exit code or catch, or review such a diff. Don't use for an operation's error list (use working-with-contracts).
How it works
- Result, throw or retry
- Catalog
- Catch at boundaries
- One shape over HTTP, CLI and MCP
- Exit codes
- Hints
- Checks
SKILL.md preview
---
name: handling-errors
description: Rules for errors - Result vs throw, retries, the ERRORS catalog, hints, exit codes, boundary catches, one shape over HTTP, CLI and MCP. Use when you add or change an error code, hint, exit code or catch, or review such a diff. Don't use for an operation's error list (use working-with-contracts).
---
# Handling errors
## Result, throw or retry
- Return a `Result` (`ok`/`err` in `packages/contracts/src/errors.ts`) when callers handle the
failure differently: `parseRef` in `packages/contracts/src/ids.ts` has three callers.
- Throw `CommandError` (`packages/core/src/app/commands.ts`) or `CliError`
(`packages/cli/src/exit-codes.ts`) when the failure ends the request.
- Translate a domain error at the layer edge: `rule` in `packages/core/src/app/blocks.ts` turns
`BlockRuleError` into `CommandError` and rethrows anything else.
- There is no `retryable` flag; retry guidance is `recovery` (`sideEffects`, `maxRetries`).
- One owner retries: the adapter runner (`nextDelay` in `packages/adapters/src/runner/policy.ts`)
and the outbox sender (`packages/core/src/app/sender.ts`). Gateways make one attempt (G1, G2 in
`packages/contracts/src/gateway/gateway.ts`).
## Catalog
- Every code is an `ERRORS` entry in `packages/contracts/src/errors.ts`; the wire fields are
`errorDetailSchema`: `code`, `requestId`, `message`, `hint`, `docs`, `recovery`, `context`,
optional `trace`.
- Adding or changing a code: follow `.agents/skills/handling-errors/references/add-a-code.md`.
## Catch at boundaries
- Catch only at a boundary: HTTP `setErrorHandler` (`packages/core/src/api/server.ts`), CLI
`runCli` (`packages/cli/src/cli.ts`), the MCP tool callback (`packages/cli/src/mcp.ts`),
`runDaemon` (`packages/daemon/src/lifecycle.ts`), and background loops: the adapter runner,
purge `onError` (`packages/daemon/src/composition.ts`), inbound dispatch, Socket Mode `track`
(`packages/gateway-slack/src/socket.ts`, reported through `onError`).
- `runDaemon` writes lock and config failures with `port.writeErr`, before a logger exists; later
failures go to the log as `{ err }`.
- A middle layer translates one known error and rethrows the rest; `logCall`
(`packages/daemon/src/logger.ts`) logs and rethrows.
- Keep the cause when you wrap: `new AdapterError(..., { cause })`
(`packages/adapters/src/github/client.ts`), `ConfigError` in `packages/daemon/src/config.ts`.
- Log a cause as `err` through `ctx.log`; a cause or stack never reaches the wire.
- HTTP, CLI and MCP turn an unknown error into `unexpected`; only HTTP logs the cause, through
`logError` as `{ err, requestId }`. `trace` names the daemon log even for a client-side
`client-<uuid>` requestId. Log the cause where you still hold it.
## One shape over HTTP, CLI and MCP
- Build error bodies only through `packages/contracts/src/error-renderers.ts`; the forms stay
equal by `packages/contracts/test/errors.test.ts` `describe('error representations')`.
- Renderers take no hint (`errorInputSchema`). HTTP (the `setErrorHandler` callback) and CLI
(`renderCliError`) patch a per-call hint after rendering; MCP (`renderMcpError`) applies one
for `forbidden` only, so the catalog hint of every other code must stand alone.
- MCP input errors are catalog `usage`: `handlerValidator` admits every argument and
`parseArguments` rejects.
- `problemError` (`packages/cli/src/client.ts`) keeps a code only when its `status` matches the
HTTP status, else `outcome_unknown`.
## Exit codes
- `EXIT_CODES`: 0 ok, 1 refused, 2 usage, 3 not applied, 4 config, 5 outcome unknown.
- 3: the daemon could not evaluate the call, so nothing applied; retry after the hint's step.
A call the daemon evaluated and rejected is 1, even if it can pass later.
- 5: it may have applied; check, then retry with the same key (`renderCliError` adds
`retry with --key`, MCP adds `idempotencyKey` to `context`).
## Hints
- `message` says what happened; `hint` is the imperative next step.
- Backticked `board <command>` spans in catalog `message`, `hint` and `recovery` are resolved by
`packages/cli/test/commands.test.ts` `describe('catalog commands')`; check `mcp` and per-call
hints by hand.
- An operator-only step says "ask the operator" or "Ask in your own session" (`forbidden`,
`daemon_unavailable`).
- No secrets, no stacks. Other text rules are checked by `packages/contracts/test/errors.test.ts`
`describe('error catalog')`.
- Add an `mcp` variant only when the agent's next step differs (`version_mismatch`).
## Checks
- `pnpm gen`, then `pnpm check`.
Files in this package (2)
- SKILL.md 4 KB
- references/add-a-code.md 3 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · AnDeVerin/spur-board | 90 | MIT |
| PRDAnvil/prd-toolkit | 100 | MIT |
| rileyhilliard/claude-essentials | 100 | MIT |
Database snapshot: 13.11.2026 · package version bda84eed102c (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
- 90error-handling-patterns
Design and review error handling in a codebase: which errors are expected results versus bugs, typed error hierarchies or result types, where to catch (boundaries) and where never to, preserving cause chains, mapping errors to HTTP and CLI exit codes, retries with backoff for… - 100result-error-handling
This skill should be used when working with Result<T,E>, BrepError, or error paths in brepjs — deciding whether to throw or return a Result, constructing errors with codes, or handling failures. Trigger phrases include "should this throw or return err", "Called unwrap() on an… - 100error-code-guide
Design consistent error codes following the PREFIX_CATEGORY_NUMBER format. Use when: defining error codes, creating error handling, designing APIs. Not for: log format and levels — use /logging-guide; handling errors that already reached production — use /incident. Keywords:… - 100error-handling
Error-handling: envelope, propagation, and capture rules for server-side APIs. TRIGGER when: reviewing server-side catch blocks, response formatters, telemetry capture, or serverless error boundaries; defining or auditing application error codes or the code registry; reviewing… - 95errors
设计一致的错误码,遵循 PREFIX_CATEGORY_NUMBER 格式。 Use when: 定义错误码、建立错误处理机制、设计 API。 Not for: 日志格式与级别——请用 /logging-guide;处理已经到达生产环境的错误——请用 /incident。 Keywords: error code, error handling, error format, API errors, 错误码, 错误处理, 错误格式. - 100error-handling
Language-neutral error handling. Classifying failures, where to catch, typed errors, propagating with context, API error responses, logging once, user vs developer messages, timeouts, retries with backoff, circuit breakers and fallbacks. Use when designing error types, adding…