Skip to content

Error Codes

Every Tryll server response that is not a normal success reply carries an ErrorResponse frame with a numeric code and a human-readable message. Codes are grouped by the layer that produces them, and each range has a characteristic recovery strategy.

This page lists every code a correctly-behaving server can emit. If a client ever receives a code not listed here, treat it as a protocol violation (server/client version mismatch) and log both the code and the message verbatim.

Error-code ranges

Range Layer Typical recovery
1xxx Connection Reconnect after backoff; session state is gone.
2xxx Session Re-send ConfigureSessionRequest; stop issuing requests if the server is shutting down.
3xxx Agent Recreate the agent or fix the graph; previous agent is no longer usable.
4xxx Inference / workflow Turn-local; other turns and other agents are unaffected.
5xxx Protocol / framing Client bug or version mismatch; stop and investigate.
6xxx Model download User-actionable (disk, network, catalog); retry once resolved.
7xxx String storage Fix the input and re-create the storage.
8xxx Embedded string storage Fix the config or inline input and re-create the storage.

The authoritative source of every code is server/common/include/tryll/ErrorCodes.h. Client libraries expose the same values: Tryll::Client::ErrorCode (C++), tryll_client.ErrorCode (Python), ETryllErrorCode (Unreal).

1xxx — Connection

These errors surface client-side only: the client failed to reach the server, lost the TCP connection, or timed out waiting for a reply. The server never emits 1xxx codes itself.

Code Name Meaning
1001 ConnectionFailed TCP connect to the configured host/port failed outright. The server process is not running or the port is blocked.
1002 ConnectionDropped The established connection was closed mid-session (peer close, socket error, network partition). Session state on the server is gone.
1003 Timeout The client gave up waiting for a response frame. The socket itself may still be healthy; typically the server is overloaded or a node hung.

Recovery: reconnect after exponential backoff; re-configure the session; recreate agents.

2xxx — Session

The server rejected a request because the session is not in the right state to accept it, or because the server is shutting down.

Code Name Meaning
2001 ServerShuttingDown The server is in graceful shutdown and no longer accepts new requests on this session. In-flight turns continue until they complete or time out.
2002 SessionNotReady The client issued a request that requires a configured session before sending ConfigureSessionRequest.

Recovery:

  • ServerShuttingDown — stop sending; close the socket; back off before attempting to reconnect.
  • SessionNotReady — send ConfigureSessionRequest first, then retry the original request.

3xxx — Agent

The request targeted an agent that does not exist, is already gone, or cannot be created because its graph is invalid.

Code Name Meaning
3001 InvalidAgentId The agent_id in the request does not match any agent the server knows about. Typically a client-side bookkeeping bug.
3002 AgentAlreadyDestroyed The agent was previously destroyed; its id is no longer valid. Any in-flight turn for that agent was cancelled.
3003 GraphCompilationFailed CreateAgentRequest carried a graph the server could not compile into an executable plan. The message field names the first validation failure.
3004 AgentBusy SendMessageRequest arrived while the agent was still processing the previous turn. Wait for TurnCompleteResponse before sending again.

Recovery:

  • 3001 / 3002 — recreate the agent with CreateAgentRequest; do not retry the original request against the bad id.
  • 3003 — fix the graph and re-create. The message points at the node or route that failed validation.
  • 3004 — wait for TurnCompleteResponse; the Tryll client libraries already serialise per-agent sends.

4xxx — Inference / workflow

Errors raised by nodes during a turn. These end the current turn with TurnStatus::Error; the agent remains usable and can accept the next turn.

Code Name Meaning
4001 InferenceFailed A Generate or other inference node raised a non-recoverable runtime error (tokenizer failure, backend crash, model unloaded unexpectedly).
4002 InferenceTimeout A node exceeded its per-node time budget. Most often a symptom of a too-large prompt on a slow inference engine.
4003 MaxStepsExceeded The workflow exceeded the maximum number of node transitions for one turn. Usually indicates an unterminated loop in the graph.

Recovery: the turn has already ended; surface the error to the user or retry the user's message. The agent can accept the next turn without recreation.

5xxx — Protocol / framing

The server could not make sense of a frame the client sent. 5xxx always indicates a client bug or a version mismatch; there is no automated recovery.

Code Name Meaning
5001 MalformedMessage The frame could not be decoded against the FlatBuffers schema.
5002 UnknownMessageType The frame's message-type tag is not in the server's known set.
5003 FrameTooLarge The frame exceeds the negotiated 1 MiB maximum.
5004 ProtocolVersionMismatch The client speaks a wire-protocol version the server cannot parse.

Recovery: none — log, escalate, and investigate. See the wire protocol reference for the framing contract.

6xxx — Model download

The server was unable to download a model. All 6xxx codes are user-actionable: fix the underlying condition (network, disk, catalog) and retry.

Code Name Meaning
6001 DownloadFailed The download transport failed (HTTP error, interrupted transfer, checksum mismatch).
6002 DownloadNotAvailable The named model has no variant for the active inference engine in the catalog.
6003 InsufficientDiskSpace The target download directory lacks free space for the model.
6004 DownloadAlreadyActive A download for this model is already in progress on the server.
6006 ModelAutoDownloadFailed CreateAgent was called with allow_auto_model_downloading=true, but a required model either has no download source configured in the catalog, or the transfer itself failed. The message field names the offending model.

Recovery:

  • 6001 — retry after checking connectivity.
  • 6002 — ask the server admin to add a matching variant to the catalog (see Use Your Own Local Model), or request a different model.
  • 6003 — free disk space or reconfigure models_download_dir.
  • 6004 — wait for the in-flight download's completion frame instead of re-issuing.
  • 6006 — inspect message for the model name; either add a huggingface_repo entry to the catalog or download the model manually before calling CreateAgent. See Enable Auto Model Downloading.

7xxx — String storage

Errors raised by CreateStringStorageRequest. The session is unchanged on failure; the storage is not created.

Code Name Meaning
7001 InvalidStringStorageName The storage name is empty, malformed, or reserved.
7002 StringStorageAlreadyExists A storage with this name is already registered for the session.
7003 InvalidStringStorageData The content was rejected: unreadable file, bad format, empty array.

Recovery: fix the name or content and re-send the request. See the string storage reference.

8xxx — Embedded string storage

Errors raised by CreateEmbeddedStringStorageRequest. The session is unchanged on failure; the storage is not created.

Code Name Meaning
8001 InvalidEmbeddedStringStorageName The storage name is empty, malformed, or reserved.
8002 EmbeddedStringStorageAlreadyExists A storage with this name is already registered for the session.
8003 InvalidEmbeddedStringStorageData The content was rejected: missing *.kb.json, missing or corrupt *.usearch, empty inline array, or an embedding model that is not in the catalog.

Recovery: fix the config or inline input and re-send the request. See the embedded string storage reference.

Client-side handling

Every Tryll client library delivers these codes through its error channel:

  • C++ — Tryll::Client::ErrorCode plus an std::string message on the on_error callback.
  • Python — raised as tryll_client.TryllError with .code and .message attributes, or delivered to the async callback.
  • Unreal — FTryllError USTRUCT with Code and Message properties; the ETryllErrorCode UENUM matches this table.