Skip to content
Skills Library
Programming · Building & coding

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

Repository
spur-board ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

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

t use for an operation
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

  1. Result, throw or retry
  2. Catalog
  3. Catch at boundaries
  4. One shape over HTTP, CLI and MCP
  5. Exit codes
  6. Hints
  7. Checks
Original SKILL.md headings · 77 lines, 535 words
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

RepositoryScoreLicence
This page · AnDeVerin/spur-board90MIT
PRDAnvil/prd-toolkit100MIT
rileyhilliard/claude-essentials100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.