Error Handling

Aleph uses typed errors at library boundaries and accumulates context in application code. Internal error chains are for diagnosis; client-facing errors must pass through the Gateway's unified user-readable receipt.

Error chains

Implementations preserve source chains so root causes, boundaries, and call context remain traceable. Logs may record the diagnostic chain, but must scrub secrets, internal paths, and sensitive payloads. User interfaces must not display raw serde_json, database, or I/O errors.

Safe truncation must respect UTF-8 character boundaries rather than cutting multi-byte text at a byte offset. Public library APIs should return typed errors; application entry points may wrap lower-level errors with context.

Gateway single source of error

The Gateway returns a single-source user-readable error receipt (ErrorReceipt) to clients. The raw error chain remains on the server's diagnostic path and is never exposed to the Panel or other clients. Clients should handle the receipt and must not parse internal error text or construct a second error protocol.

This boundary covers configuration, session, tool, provider, WebSocket/HTTP, and storage errors. The Gateway may log the complete source chain server-side, but logs and receipts are separate output surfaces.

Fail closed

Authorization must be denied when a policy file is missing, unreadable, or invalid. Errors must never turn the default behavior into fail-open.

Related locations

• src/error.rs: cross-module error definitions and conversions
• src/gateway/: Gateway boundary and client receipts
• src/config/, src/session/, src/tools/, src/providers/: domain errors
• Gateway Protocol Errors
• Logging