Error codes

Riverbeam errors are Riverbase errors. Each has a stable code BEM-NNN, an HTTP status, and a user-safe message; errdata adds the detail, such as the agent name or the underlying cause. The shape and the HTTP problem format are described in Riverbase errors.

Serialized with serde_json, as a worker sends it over NATS and as the API examples on this site return it, an error looks like this:

{
  "http_status": 404,
  "http_title": "Not Found",
  "errcode": "BEM-020",
  "errmesg": "That agent is not registered.",
  "errdata": "kb-assistant"
}

A worker replies with {"error": <RiverbaseError>}, and NatsWorkerClient rebuilds the error with its code, status, message, data and hint. Map http_status to the response status in your HTTP layer. Routes mounted through a Riverbase app render errors as problem documents instead; see Riverbase errors.

The errors most clients see:

Code	Status	When
BEM-020	404	agent_name is not registered
BEM-040	400	The content uses a modality the agent does not support
BEM-060	403	The user's usage plan blocked the request
BEM-061	403	A security rule blocked the request or the reply
BEM-067	403	The authorization policy denied the command
BEM-063, BEM-066	400	A resume request names an invalid or already resolved action
BEM-027	404	A resume request names an action that does not exist
BEM-096	500	The API's NATS request to a worker failed or timed out

Requests and payloads

Serialization and payload validation.

Code	Status	Message
BEM-001	422	Failed to serialize the beam invoke request.
BEM-002	422	Failed to encode the worker task payload for NATS.
BEM-003	422	The invoke_agent worker payload is not a valid invoke request.
BEM-004	422	Knowledge ingest requires inline text; media and URL ingest are host-bound.
BEM-005	422	Knowledge delete requires a valid document_id.
BEM-006	422	Report queries are not supported for this beam resource.

Not found

Agents, commands, resources and actions that do not exist.

Code	Status	Message
BEM-020	404	That agent is not registered.
BEM-021	404	That agent is not registered for stream dispatch.
BEM-022	404	The invoke pipeline could not resolve the requested agent.
BEM-023	404	That agent is not in the beam catalog.
BEM-024	404	That command is not registered in the beam domain.
BEM-025	404	That query resource is not registered in the beam domain.
BEM-026	404	That catalog item was not found.
BEM-027	404	That agent action was not found.
BEM-028	404	That agent action could not be resolved because it was not found.

Routing and knowledge setup

Modalities, models, the routing file, and the knowledge subsystem.

Code	Status	Message
BEM-040	400	The agent does not support the requested input modalities.
BEM-041	422	No model is available for this request.
BEM-042	500	The selected model configuration is invalid.
BEM-043	500	Failed to read the model routing YAML file.
BEM-044	500	Failed to parse the model routing YAML file.
BEM-045	501	The knowledge subsystem is not configured on this worker.
BEM-046	500	Failed to serialize the agent invoke result.
BEM-047	500	Failed to serialize the knowledge ingest result.

Policy and resume

Quota, security, authorization, and human-approval resume checks.

Code	Status	Message
BEM-060	403	The usage quota for this request has been exceeded.
BEM-061	403	A security rule blocked this request.
BEM-062	400	Resume requires the pending interaction identifier.
BEM-063	400	Resume received an invalid action identifier.
BEM-064	400	Resume referenced an unknown pending action.
BEM-065	400	Resume action does not belong to the pending interaction.
BEM-066	400	Resume action is not pending.
BEM-067	403	This beam command is not allowed for the current subject.

Agent execution

Completion clients, the agent stream, and the tool loop.

Code	Status	Message
BEM-080	422	The scripted completion client lock was poisoned.
BEM-081	422	The scripted completion client has no remaining steps.
BEM-082	422	The language-model completion request failed.
BEM-083	422	The language-model completion response could not be decoded.
BEM-084	422	The language-model completion returned an error status.
BEM-085	422	The language-model completion response has no choices.
BEM-086	422	The agent stream ended without a terminal done frame.
BEM-087	422	The agent stream reported an error frame.
BEM-088	422	The agent tool loop exceeded the maximum number of steps.
BEM-089	422	The agent requested an unknown tool during the tool loop.
BEM-090	422	The agent requested an unknown tool while resuming actions.

Worker, transport and sandbox tools

Worker tasks, NATS, stream publishing, and sandbox tool arguments.

Code	Status	Message
BEM-091	404	That worker task is not registered.
BEM-092	501	That worker memory task is not implemented yet.
BEM-093	500	The worker failed to connect to NATS.
BEM-094	500	The worker failed to subscribe to NATS task subjects.
BEM-095	500	The domain client failed to connect to NATS.
BEM-096	500	The domain client failed to request a worker task over NATS.
BEM-097	500	The domain client failed to publish a worker task over NATS.
BEM-098	500	The worker reply payload is not valid JSON.
BEM-099	500	The worker reply envelope is missing a result or a structured error.
BEM-100	500	The worker error payload is not a structured Riverbase error.
BEM-101	500	The stream transport failed to connect to NATS.
BEM-102	500	The stream transport failed to subscribe to a NATS channel.
BEM-103	500	Failed to serialize a stream frame for NATS.
BEM-104	500	Failed to publish a stream frame to NATS.
BEM-105	422	Failed to publish an agent stream chunk.
BEM-106	422	Failed to publish the agent stream completion frame.
BEM-107	422	Sandbox tools require metadata.sandbox_root when no working tree is bound.
BEM-108	422	A required sandbox tool argument is missing.
BEM-109	501	The remember tool must be bound by the host memory manager.

Execution store

BeamStore and PgBeamStore.

Code	Status	Message
BEM-110	500	Failed to establish the beam store database pool.
BEM-111	500	Could not get a database connection to apply beam store schema.
BEM-112	500	Failed to apply the beam store schema.
BEM-113	500	Could not get a database connection for the beam store.
BEM-114	500	Failed to check in beam agents.
BEM-115	500	Failed to check in beam models.
BEM-116	500	Failed to ensure a beam session row.
BEM-117	500	Failed to update beam session activity.
BEM-118	500	Failed to create a beam interaction.
BEM-119	500	Failed to complete a beam interaction.
BEM-120	500	Failed to create a beam run.
BEM-121	500	Failed to complete a beam run.
BEM-122	500	Failed to save a beam message.
BEM-123	500	Failed to allocate the next beam message sequence.
BEM-124	500	Failed to create a beam action.
BEM-125	500	Failed to load a beam action.
BEM-126	500	Failed to resolve a beam action.
BEM-127	500	Failed to load a beam session.
BEM-128	500	Failed to load a beam interaction.
BEM-129	500	Failed to load a beam run.
BEM-130	500	Failed to list beam messages.
BEM-131	500	The in-memory beam store write lock was poisoned.
BEM-132	500	The in-memory beam store read lock was poisoned.

Memory

The in-memory memory backend.

Code	Status	Message
BEM-140	500	The in-memory memory backend could not load a layer because the lock was poisoned.
BEM-141	500	The in-memory memory backend could not append a layer because the lock was poisoned.
BEM-142	500	The in-memory memory backend could not forget an item because the lock was poisoned.

Knowledge store

InMemoryVectorStore and PgVectorStore.

Code	Status	Message
BEM-200	500	The in-memory knowledge store could not upsert records because the lock was poisoned.
BEM-201	500	The in-memory knowledge store could not query records because the lock was poisoned.
BEM-202	500	The in-memory knowledge store could not delete records because the lock was poisoned.
BEM-203	500	Failed to establish the knowledge store database pool.
BEM-204	500	Could not get a database connection for the knowledge store.
BEM-205	500	Could not get a database connection to apply knowledge schema.
BEM-206	500	Failed to apply the knowledge store schema.
BEM-207	422	A knowledge record is missing a document_id UUID.
BEM-208	500	Failed to upsert a knowledge document row.
BEM-209	500	Failed to upsert a knowledge chunk row.
BEM-210	500	Failed to upsert a knowledge memory row.
BEM-211	500	Failed to query knowledge chunks.
BEM-212	500	Failed to query knowledge memory rows.
BEM-213	500	Failed to delete a knowledge chunk by id.
BEM-214	500	Failed to delete knowledge chunks by document.
BEM-215	500	Failed to delete a knowledge memory row.

Embedders and knowledge configuration

HTTP embedders and the knowledge factory.

Code	Status	Message
BEM-220	500	The embedder returned an empty result for the query text.
BEM-221	500	The embedder HTTP request failed.
BEM-222	500	The embedder HTTP response could not be decoded.
BEM-223	500	The embedder HTTP request returned an error status.
BEM-224	500	The embedder response is missing the data array.
BEM-225	500	The embedder response is missing an embedding array.
BEM-226	500	An embedding vector width does not match the configured dimension.
BEM-227	500	The embedder returned a different number of embeddings than requested.
BEM-230	422	Knowledge ingest produced no chunks.
BEM-231	500	An HTTP embedder was requested without an API key.
BEM-232	500	HashEmbedder cannot write into a pgvector store.
BEM-233	500	The embedder dimension does not match KNOWLEDGE_EMBEDDING_DIM.
BEM-234	500	pgvector knowledge storage requires a 1536-dimension embedding.

Sandbox and git

SandboxRoot paths and WorkingTree git operations.

Code	Status	Message
BEM-300	400	The sandbox path is absolute, contains NUL, or uses a forbidden separator.
BEM-301	400	The sandbox path contains a parent-directory component.
BEM-302	400	The resolved sandbox path escapes the jail.
BEM-303	400	The sandbox parent path escapes the jail.
BEM-304	400	The sandbox path is missing a file name.
BEM-305	400	The joined sandbox path is not under the jail root.
BEM-306	400	The sandbox path is not a directory.
BEM-307	500	Failed to read a file inside the sandbox.
BEM-308	400	Creating the sandbox write parent escaped the jail.
BEM-309	400	A listed sandbox path could not be stripped to a jail-relative path.
BEM-310	500	Failed to create the sandbox root directory.
BEM-311	500	Failed to canonicalize the sandbox root.
BEM-312	500	Failed to canonicalize an existing sandbox path.
BEM-313	500	Failed to canonicalize a sandbox parent path.
BEM-314	500	Failed to create directories while writing a sandbox file.
BEM-315	500	Failed to canonicalize a sandbox write parent.
BEM-316	500	Failed to write a file inside the sandbox.
BEM-317	500	Failed to read a sandbox directory entry.
BEM-318	500	Failed to read a sandbox directory listing.
BEM-320	500	Failed to initialize a git repository in the sandbox.
BEM-321	500	Failed to open the sandbox git repository.
BEM-322	500	Failed to read git status in the sandbox.
BEM-323	500	Failed to compute a git diff in the sandbox.
BEM-324	500	Failed to read the git log in the sandbox.
BEM-325	500	Failed to stage files in the sandbox git repository.
BEM-326	500	Failed to create a git commit in the sandbox.
BEM-327	500	Failed to read the current git branch in the sandbox.
BEM-328	403	Pushing a protected git ref is not allowed.
BEM-329	500	The sandbox git repository has no origin remote.
BEM-330	500	Failed to push a git ref from the sandbox.
BEM-331	500	Failed to add or update the sandbox git origin remote.
BEM-332	500	Failed to check out a git branch in the sandbox.

Audio

Audio decoding, speech-to-text, and the audio turn.

Code	Status	Message
BEM-350	400	The audio bytes are missing a RIFF/WAVE header.
BEM-351	400	The WAV payload has no data chunk.
BEM-352	422	WebM or MP4 decode requires a host decoder; fixture tests use WAV.
BEM-353	422	The audio container is not supported.
BEM-354	422	The audio turn received empty audio bytes.
BEM-355	500	HTTP speech-to-text requires a base URL.
BEM-356	500	Failed to build the speech-to-text multipart body.
BEM-357	500	The speech-to-text HTTP request failed.
BEM-358	500	The speech-to-text HTTP response could not be decoded.
BEM-359	500	The speech-to-text HTTP request returned an error status.
BEM-360	500	The audio turn failed to invoke the agent.

BEM-064 and BEM-065 are declared but not raised yet, and BEM-062 cannot occur through invoke. See Sessions and human approval.