Barrel
FR GitHub

Error codes

This page lists the errors you can get back, what they mean and what to do. REST errors are JSON bodies {"error": "<code>"} with an HTTP status; the Erlang API returns {error, Reason}. Use it when a call fails and you need the fix, not the cause; Troubleshooting starts from the symptom instead.

How REST errors look

{"error": "conflict"}

Some codes add fields: reason (a bad /find body, bad att_opts), message, line and column (a BQL syntax error), current (an attachment conflict), tokens (missing_bodies).

Note

An error the server does not map becomes a 500 with the Erlang term printed as the error string, for example {"error":"{dimension_mismatch,768,2}"}. That is why some configuration problems answer 500 rather than 4xx.

Authentication

StatuserrorMeaning and fix
401unauthorizedNo token, a wrong, unknown or revoked token, or a bad or replayed signature. The response carries www-authenticate: Bearer. Send Authorization: Bearer with a valid token, or sign again.
401signature_v3_requiredA v1 or v2 signature on a request that carries a write header or writes an attachment. Sign with v3.
401content_hash_mismatchThe body does not match its signed hash in x-barrel-content-sha256. Hash the exact bytes you send.
400bad_bodyThe body of a signed request could not be read. Retry.
403forbiddenThe capability token lacks the right, is for another space, or the route accepts only a server token.
413too_largeA signed body over max_body (1 GiB by default).

Databases and documents

StatuserrorMeaning and fix
400invalid_nameThe name breaks the rule: use lowercase letters, digits, _ and -, 1 to 63 bytes, not starting with _. barrel_server before 1.14.0 answered 500 invalid_db_name for uppercase names.
404db_not_foundThe database does not exist. Only PUT /db/:db (or the MCP tool db_create) creates one; create it first.
400bad_att_opts + reasonBad att_opts in the body of PUT /db/:db.
404not_foundThe document, version or attachment does not exist.
409conflictThe _rev you sent is not current. Read again and retry with the new _rev.
400bad_jsonThe body is not JSON.
400invalid_provenanceAn x-barrel-actor, x-barrel-session or x-barrel-source header is too long (256 bytes each, 1 KiB together).
400bad_since, bad_until, bad_limitA bad query parameter on GET /db/:db/_history.

GET /db/:db/changes with a bad since does not fail: it restarts from the first change.

Queries

StatuserrorMeaning and fix
400invalid_query + message, line, columnBQL syntax error. BQL has no COUNT or GROUP BY.
400invalid_query + reasonAn unknown key in a /find body, or a malformed continuation. Send back the continuation from meta as it came.
400missing_queryA JSON body without query.
400invalid_max_rows, invalid_deadline_msNot a positive integer (at most 1000 rows, 300000 ms).
400subscribe_requires_sseA SUBSCRIBE statement without Accept: text/event-stream or ?feed=sse.
in streamdeadlineThe deadline passed after some rows were sent; the last NDJSON line is {"error":"deadline"}.

These are configuration problems, but they answer 500.

StatuserrorMeaning and fix
500bm25_not_enabledKeyword search is off on this database. Open it with vectordb => #{bm25_backend => disk}, or use record mode.
500embedder_not_configuredNo embedder to turn your text into a vector. Configure one, or send a vector.
500{dimension_mismatch,768,N}Your vector has N dimensions; the store expects 768.

Attachments

StatuserrorMeaning and fix
409conflict + currentAn If-Match or If-None-Match: * condition failed.
400bad_if_none_matchOnly * is allowed in If-None-Match.
501attachments_disabledThe database was created with att_opts => #{backend => none}.
501conditional_writes_unsupportedThe S3 backend cannot do conditional writes (Garage).
503att_sync_pendingA new S3-backed branch is still copying. Retry shortly.

Branches

StatuserrorMeaning and fix
400invalid_nameA bad branch name.
400bad_atat is not a changes cursor, or at_time is not RFC 3339.
400pitr_window_exceededThe instant is older than the retained history.
409already_existsA branch with that name exists.
409cannot_branch_a_branchBranch the parent instead.
409not_a_branchMerge was called on a database that is not a branch.
404parent_not_foundThe branch's parent is not open.

Replication wire

StatuserrorMeaning and fix
404not_foundThe database does not exist; replication never creates one.
409clock_skewThe sender's clock is too far ahead.
400bad_hlc, bad_state, bad_bodies, missing_bodies + tokens, bad_json, bad_filter, bad_since, bad_touch, bad_originA malformed sync request.
403read_onlyA repair sent to a read-only database.
412bytes_neededAn attachment upload without its bytes.
422digest_mismatchAttachment bytes do not match x-barrel-digest.
413too_largeThe attachment is too large.
501att_flush_unsupported, att_sync_unsupported, attachments_disabledThis server's attachment backend lacks the feature.
406not_acceptableThe request asked for a format the route does not serve.

Spaces and handoffs

StatuserrorMeaning and fix
401unauthorizedThe token is invalid, revoked or expired.
403forbiddenThe token is for another space, or lacks the right.
404space_droppedThe space was dropped.
409already_accepted, already_completedThe handoff token was already used.
400task_name_required, missing_space, missing_token, invalid_message, invalid_rights, invalid_expires_at, bad_rangeA missing or bad field. Empty rights also gives invalid_rights.

Contexts

Context and working-set routes answer {"error", "message", "hint", "details"}. The codes come from barrel_ctx_error:codes/0:

Statuserror
400invalid_argument, invalid_query, limit_required, limit_too_large, too_many_contexts, duplicate_context, unsupported_federated_query, merge_not_allowed, merge_not_supported, scores_not_comparable, invalid_card, no_location, invalid_snapshot
403forbidden
404unknown_context, unknown_working_set, not_attached
409ambiguous_context, already_attached, already_exists, offline
413over_budget
502source_unavailable
500internal

A member that fails is reported in sources[] of the answer, not as a request error.

MCP

A request without a token on a locked server is HTTP 401. Tool errors come back as a tool result with isError: true and the same JSON body, for example {"error":"not_found"} or {"error":"forbidden","db":"kb"}.

Erlang API

Lifecycle and documents

ReturnMeaning and fix
{error, already_exists}create_db on an open database. Use open_db/1.
{error, invalid_db_name}Lowercase letters, digits, _ and -, 1 to 63 bytes. A leading _ is reserved for barrel's own databases.
{error, not_found}A missing document, or a database that is not running.
{error, {db_failed, Reason}}The database's writer crashed 3 times in 60 seconds. Fix Reason, then reopen_db/1.
{error, conflict}A stale _rev.
{error, read_only}A write on a database opened with read_only => true.
{error, clock_skew}The clock is behind the database's newest write, or a remote HLC was refused. Fix the clock.
{error, {invalid_expires_at, V}}expires_at must be a non-negative unix time in milliseconds.
{error, {invalid_provenance, _}}Provenance fields too long.
{error, {invalid_condition, C}}A bad find condition.
{error, db_restarted}An attachment stream or upload outlived a database restart. Open it again; the upload published nothing.
{error, upload_expired}An upload left open longer than att_upload_timeout (3600 s).
{error, {read_only_upgrade_needed, _}}Stores that need an upgrade, opened read only. Open once writable.

BQL

ReturnMeaning and fix
{error, {parse_error, {Line, Col}, Msg}}A syntax error, from barrel_docdb:query/2,3.
{error, {invalid_query, {Line, Col}, Code}}A statement the grammar accepts but the compiler refuses. See BQL.
{error, {table_fn_requires_barrel, Fn}}Search table functions run only through barrel:query/2,3.
{error, {unsupported, subscribe}}SUBSCRIBE through query; use subscribe_query/2,3.
{error, {limit_required, #{max_limit := 1000}}}A context query without LIMIT.

barrel module

ReturnMeaning and fix
{error, no_vector_store}A vector call, or an export, on a database opened with vectordb => none.
{error, record_mode}vector_add on a record-mode database; write the document instead.
{error, mixed_batch}A vector_add_batch/2 list that mixes entries with and without vectors.
{error, {invalid_option, vectordb}}embedding together with vectordb => none.
{error, no_stored_policy}embedding => stored on a database that never ran in record mode.
{error, barrel_app_not_started}Record mode needs the barrel application started.
{error, {unknown_options, Keys}}Unknown keys in an embedding policy.
{error, {dimension_mismatch, Want, Got}}A vector of the wrong length.
{error, {index_init_failed, faiss_not_available}}backend => faiss without the barrel_faiss NIF.

Encryption

ReturnMeaning and fix
{error, db_is_encrypted}Pass the encryption spec when opening.
{error, wrong_encryption_key}The key does not match this database.
{error, cannot_encrypt_existing_db}No in-place encryption. Create an encrypted database and replicate into it.
{error, {key_provider_error, barrel_keyprovider_env, no_encryption_key}}BARREL_ENCRYPTION_KEY is not set.

Timeline

ReturnMeaning and fix
{error, not_a_branch}, {error, parent_not_found}Merge on a database that is not a branch, or whose parent is not open.
{error, already_exists}, {error, branch_dir_exists}The branch name or its folder is taken.
{error, cannot_branch_a_branch}Branch the parent.
{error, pitr_window_exceeded}, {error, {pitr_window_exceeded, DocId}}The instant, or that document's history, is older than retention.
{error, {bad_at, future}}, {error, {bad_at, _}}The instant is in the future, or not a valid HLC.

Replication

ReturnMeaning and fix
{error, {checkpoint_failed, target, not_found}}The local target database does not exist. Create it first.
{error, not_found}The remote database does not exist (HTTP 404).
{error, unauthorized}The remote answered 401.
{error, clock_skew}The remote answered 409 with {"error":"clock_skew"}. Any other 409 comes back as {error, {http, 409, Body}}.
{error, too_large}, {error, {http, Status, Body}}The remote answered 413, or another status.
{error, {inline_credentials, Keys}}Move credentials from the task to sync_auth, sync_signing or sync_ssl.
{error, att_flush_unsupported}The target cannot make attachment writes durable; upgrade it or pass att_durability => best_effort.
{error, {att_flush_failed, R}}, {error, {att_sync_failed, R}}The attachment phase failed; the checkpoint stays before it.
{error, att_filter_unsupported}The source server cannot filter attachments.
{error, too_many_failed_docs}More than 1000 documents failed in one run; the checkpoint did not move.
{error, not_running}get_task_pid/1 on a task that is not running.

Embedding and reranking

ReturnMeaning and fix
{error, embedder_not_configured}No embedder in the configuration.
{error, no_providers_available}Every provider in the chain failed to start.
{error, all_providers_failed}Every provider failed on this call.
{error, venv_not_found}The managed Python venv is missing.
{error, {port_open_failed, enoent}}barrel_rerank could not start Python; pass an absolute python.

Spaces and capabilities

ReturnMeaning and fix
{error, invalid_token}Unknown or tampered token.
{error, revoked}Revoked, or a handoff token after complete.
{error, expired}Past expires_at.
{error, wrong_space}A token for another space (403 over REST).
{error, forbidden}The right is not granted (read, then write, then admin).
{error, space_dropped}The space was dropped.
{error, already_accepted}, {error, already_completed}The handoff was already used.
{error, {embedder_mismatch, _}}, {error, {embedder_required, _}}open_space with an embedder that differs from the space's, or without one when the space needs it.

S3 attachments

ReturnMeaning and fix
{error, {att_store_open_failed, missing_bucket}}att_opts without bucket. The bucket must exist.
{error, {conflict, Info}}A create_only or expected_etag write lost.
{error, conditional_writes_unsupported}The store cannot do conditional writes.
{error, {att_sync_pending, _}}A new branch is still copying its attachments.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open