Error Taxonomy & Remediation

Overview

The daemon's failure modes are deliberately closed unions so SDK consumers can exhaustively switch and route handlers can shape consistent HTTP responses. This doc catalogues every typed error class / kind across three layers:

1. packages/cli/src/serve/ — boundary errors at the HTTP edge (auth, workspace filesystem, daemon-host preflight).
2. packages/acp-bridge/ — bridge / mediator errors at the daemon-to-ACP-child boundary.
3. packages/sdk-typescript/src/daemon/ — SDK-side wrapping and structured error fields.

Wire-level error shapes are documented in ../qwen-serve-protocol.md; this doc adds cause and remediation guidance.

Filesystem boundary (packages/cli/src/serve/fs/errors.ts)

FsError carries { kind, message, status, cause? }. FsErrorKind union (14 kinds, default HTTP status):

The io_error vs permission_denied distinction is deliberate so monitoring pipelines can route on errorKind; folding ENOSPC into permission_denied would page security responders for a df -h problem.

Bridge errors (packages/acp-bridge/src/bridgeErrors.ts)

Typed classes thrown by the bridge / mediator. Most carry an HTTP status via the route handler's switch.

Boot-time configuration errors (packages/cli/src/serve/runQwenServe.ts)

Device Flow auth (packages/cli/src/serve/auth/deviceFlow.ts)

Daemon-host error kinds (packages/acp-bridge/src/status.ts)

SERVE_ERROR_KINDS is the closed enum used by diagnostic cells and structured daemon errors:

These are surfaced through the preflight cell's errorKind so client UIs render structured remediation (not raw stack traces).

Auth error shapes

See 12-auth-security.md for the full auth model.

Permission outcomes (wire vs audit overload)

PermissionResolution has two terminal kinds:

• {kind: 'option', optionId} — a vote won.
• {kind: 'cancelled', reason: 'timeout' \| 'session_closed' \| 'agent_cancelled'} — request was cancelled. The wire shape is single ({outcome: 'cancelled'}); the audit log distinguishes timeout / session_closed / voter-cancelled / agent-cancelled in decisionReason.type. This overload is preserved deliberately to avoid breaking the frozen permission.ts contract.

SDK-side error wrapping

DaemonClient returns HTTP errors as rejected Promises with the parsed body as the rejection value. Methods that hit 404 for unknown sessions reject with {error, sessionId}; the SDK does not wrap them in a typed class today. Callers should not rely on instanceof Error plus .message.includes(...) matching; switch on err.code or err.kind from the body instead.

parseSseStream aborts the iterator on 16-MiB buffer overflow (defensive bound).

Workflow

Surface an error to a user

flowchart LR
    A[HTTP 4xx/5xx body] --> B["switch on body.code OR errorKind"]
    B --> C["Render remediation per this doc's table"]
    B --> D["fallback: render body.error as toast"]

Distinguish auth failure modes

flowchart TD
    A["401 received"] --> B{"body.code == 'token_required'?"}
    B -->|yes| C["mutation-gate strict — guide user to --token / --require-auth"]
    B -->|no| D["plain Unauthorized — generic 'check token' UI"]

Dependencies

• All error classes are exported from their respective packages; SDK consumers can instanceof against bridgeErrors.ts types when running in the same Node process. Across the wire, route on body.code / body.kind / body.errorKind.

Caveats & Known Limits

• io_error vs permission_denied are distinct on purpose. Do not conflate.
• PermissionForbiddenError reasons (designated_mismatch / remote_not_allowed) are overloaded across the designated and consensus policies; the audit log distinguishes them precisely but the wire form does not.
• CancelSentinelCollisionError indicates an agent-side bug, not a security event — the bridge refuses the request rather than silently letting the sentinel match a real option.
• SDK-side typed errors are still evolving. Callers should route on body fields rather than relying on JS class identity through the wire.
• internal_error should always be investigated. It signals an FsError constructor was called with a kind reserved for non-errno paths (programmer error); the response body's cause field may carry the original throw.

References

• packages/cli/src/serve/fs/errors.ts (FsErrorKind, FsErrorStatus)
• packages/acp-bridge/src/bridgeErrors.ts (every typed class)
• packages/acp-bridge/src/status.ts (SERVE_ERROR_KINDS, ServeErrorKind)
• packages/cli/src/serve/auth.ts (auth bodies)
• Wire reference: ../qwen-serve-protocol.md.