Chat Message Error Schema#

ChatMessageError is the canonical error shape attached to a chat message record. It is defined in packages/types/src/message/common/base.ts and validated at API boundaries via ChatMessageErrorSchema (a Zod schema in the same file).

Interface and Schema#

The ChatMessageError interface carries:

The type field is the only required field in both the TypeScript interface and the Zod schema 1. The Zod validator accepts z.union([z.string(), z.number()]) to accommodate both string-keyed and numeric error codes 2.

Allowed type Values#

type is a union of three independently maintained enumerations 3:

• ILobeAgentRuntimeErrorType — runtime/provider errors from AgentRuntimeErrorType, e.g. RateLimitExceeded, ExceededToolLimit, ProviderBizError, DatabasePersistError
• ErrorType — chat-level and HTTP errors from ChatErrorType, e.g. InvalidAccessCode, FreePlanLimit, 500, 502
• IToolErrorType — tool plugin errors from ToolErrorType; currently only PluginSettingsInvalid

API Validation#

UpdateMessageParamsSchema (used by the message.update tRPC mutation) embeds ChatMessageErrorSchema as a nullish field 4. The message.update handler validates input against this schema before passing it to MessageService.updateMessage.

Error Normalization and Enrichment#

The central normalization point is formatErrorForState in apps/server/src/modules/AgentRuntime/formatErrorForState.ts. It handles four input shapes:

1. ChatCompletionErrorPayloadLike (has errorType) — extracts message from nested body layers, promotes errorType → type
2. Already-normalized ChatMessageError (has string/number type, not an Error instance) — passes through to enrichment
3. Error instance — wraps with type: ChatErrorType.InternalServerError
4. Arbitrary thrown value — wraps as AgentRuntimeErrorType.AgentRuntimeError

After normalization, enrichWithSpec looks up the type string in ERROR_CODE_SPECS (via getErrorCodeSpec from @lobechat/model-runtime) and stamps all classification fields (attribution, category, severity, retryable, countAsFailure, isFallback, numericId) in one place. This ensures all downstream consumers — DB JSONB columns, S3 snapshots, gateway WebSocket pushes, dashboards — receive a consistently enriched shape without re-running classification 5.

Persistence via Message Updates#

Errors are written to the assistant message record in CompletionLifecycle.dispatchHooks:

1. When a completion operation ends with reason === 'error' and the message ID is present, formatErrorForState is called on state.error
2. The result is persisted via messageModel.update(assistantMessageId, { error: { ...messageError, body: ..., message: ... } })
3. The error field maps to UpdateMessageParams.error: ChatMessageError | null 6, which flows through the tRPC message.update endpoint

MCP Tool Call Errors#

MCP tool failures produce ToolExecutionResult error objects with a code string (not yet ChatMessageError shaped) in ToolExecutionService.executeMCPTool:

These { code, message } objects are normalized into ChatMessageError further up the call stack via normalizeExecutionError 7 and eventually formatErrorForState before being written to the message record.

Key Files#