Barrel
EN GitHub

Codes d’erreur

Cette page liste les erreurs que vous pouvez recevoir, leur signification et quoi faire. Les erreurs REST sont des corps JSON {"error": "<code>"} avec un statut HTTP ; l’API Erlang renvoie {error, Reason}. Utilisez-la quand un appel échoue et que vous cherchez la correction, pas la cause ; Dépannage part au contraire du symptôme.

La forme des erreurs REST

{"error": "conflict"}

Certains codes ajoutent des champs : reason (un corps /find invalide, des att_opts invalides), message, line et column (une erreur de syntaxe BQL), current (un conflit de pièce jointe), tokens (missing_bodies).

Remarque

Une erreur que le serveur ne traduit pas devient un 500 avec le terme Erlang imprimé dans la chaîne error, par exemple {"error":"{dimension_mismatch,768,2}"}. C’est pourquoi certains problèmes de configuration répondent 500 plutôt que 4xx.

Authentification

StatuterrorSignification et correction
401unauthorizedPas de token, un token faux, inconnu ou révoqué, ou une signature invalide ou rejouée. La réponse porte www-authenticate: Bearer. Envoyez Authorization: Bearer avec un token valide, ou signez à nouveau.
401signature_v3_requiredUne signature v1 ou v2 sur une requête qui porte un en-tête d’écriture ou écrit une pièce jointe. Signez en v3.
401content_hash_mismatchLe corps ne correspond pas à son hash signé dans x-barrel-content-sha256. Calculez le hash des octets exacts que vous envoyez.
400bad_bodyLe corps d’une requête signée n’a pas pu être lu. Réessayez.
403forbiddenLe jeton de capacité n’a pas le droit, est pour un autre espace, ou la route n’accepte qu’un token serveur.
413too_largeUn corps signé au-delà de max_body (1 Gio par défaut).

Bases et documents

StatuterrorSignification et correction
400invalid_nameLe nom ne suit pas la règle : utilisez des lettres minuscules, des chiffres, _ et -, de 1 à 63 octets, sans _ en premier. Avant la 1.14.0, barrel_server répondait 500 invalid_db_name aux noms en majuscules.
404db_not_foundLa base n’existe pas. Seul PUT /db/:db (ou l’outil MCP db_create) en crée une ; créez-la d’abord.
400bad_att_opts + reasonDes att_opts invalides dans le corps de PUT /db/:db.
404not_foundLe document, la version ou la pièce jointe n’existe pas.
409conflictLe _rev envoyé n’est pas le courant. Relisez et réessayez avec le nouveau _rev.
400bad_jsonLe corps n’est pas du JSON.
400invalid_provenanceUn en-tête x-barrel-actor, x-barrel-session ou x-barrel-source est trop long (256 octets chacun, 1 Kio ensemble).
400bad_since, bad_until, bad_limitUn paramètre de requête invalide sur GET /db/:db/_history.

GET /db/:db/changes avec un since invalide n’échoue pas : il repart du premier changement.

Requêtes

StatuterrorSignification et correction
400invalid_query + message, line, columnErreur de syntaxe BQL. BQL n’a ni COUNT ni GROUP BY.
400invalid_query + reasonUne clé inconnue dans un corps /find, ou une continuation mal formée. Renvoyez la continuation de meta telle quelle.
400missing_queryUn corps JSON sans query.
400invalid_max_rows, invalid_deadline_msPas un entier positif (1000 lignes au plus, 300000 ms).
400subscribe_requires_sseUne instruction SUBSCRIBE sans Accept: text/event-stream ni ?feed=sse.
dans le fluxdeadlineL’échéance est passée après l’envoi de quelques lignes ; la dernière ligne NDJSON est {"error":"deadline"}.

Recherche

Ce sont des problèmes de configuration, mais ils répondent 500.

StatuterrorSignification et correction
500bm25_not_enabledLa recherche par mots-clés est désactivée sur cette base. Ouvrez-la avec vectordb => #{bm25_backend => disk}, ou utilisez le mode enregistrement.
500embedder_not_configuredAucun embedder pour transformer votre texte en vecteur. Configurez-en un, ou envoyez un vecteur.
500{dimension_mismatch,768,N}Votre vecteur a N dimensions ; le magasin en attend 768.

Pièces jointes

StatuterrorSignification et correction
409conflict + currentUne condition If-Match ou If-None-Match: * a échoué.
400bad_if_none_matchSeul * est accepté dans If-None-Match.
501attachments_disabledLa base a été créée avec att_opts => #{backend => none}.
501conditional_writes_unsupportedLe backend S3 ne sait pas faire d’écritures conditionnelles (Garage).
503att_sync_pendingUne nouvelle branche adossée à S3 est encore en cours de copie. Réessayez un peu plus tard.

Branches

StatuterrorSignification et correction
400invalid_nameUn nom de branche invalide.
400bad_atat n’est pas un curseur du flux de changements, ou at_time n’est pas en RFC 3339.
400pitr_window_exceededL’instant est plus ancien que l’historique conservé.
409already_existsUne branche de ce nom existe.
409cannot_branch_a_branchCréez plutôt la branche depuis le parent.
409not_a_branchLa fusion a été appelée sur une base qui n’est pas une branche.
404parent_not_foundLe parent de la branche n’est pas ouvert.

Protocole de réplication

StatuterrorSignification et correction
404not_foundLa base n’existe pas ; la réplication n’en crée jamais.
409clock_skewL’horloge de l’émetteur est trop en avance.
400bad_hlc, bad_state, bad_bodies, missing_bodies + tokens, bad_json, bad_filter, bad_since, bad_touch, bad_originUne requête de synchronisation mal formée.
403read_onlyUne réparation envoyée à une base en lecture seule.
412bytes_neededUn envoi de pièce jointe sans ses octets.
422digest_mismatchLes octets de la pièce jointe ne correspondent pas à x-barrel-digest.
413too_largeLa pièce jointe est trop grande.
501att_flush_unsupported, att_sync_unsupported, attachments_disabledLe backend de pièces jointes de ce serveur n’a pas la fonctionnalité.
406not_acceptableLa requête demande un format que la route ne sert pas.

Espaces et passations

StatuterrorSignification et correction
401unauthorizedLe token est invalide, révoqué ou expiré.
403forbiddenLe token est pour un autre espace, ou n’a pas le droit.
404space_droppedL’espace a été supprimé.
409already_accepted, already_completedLe token de passation a déjà été utilisé.
400task_name_required, missing_space, missing_token, invalid_message, invalid_rights, invalid_expires_at, bad_rangeUn champ manquant ou invalide. Des rights vides donnent aussi invalid_rights.

Contextes

Les routes de contextes et d’ensembles de travail répondent {"error", "message", "hint", "details"}. Les codes viennent de barrel_ctx_error:codes/0 :

Statuterror
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

Un membre en échec est signalé dans sources[] de la réponse, pas comme une erreur de requête.

MCP

Une requête sans token sur un serveur verrouillé reçoit un HTTP 401. Les erreurs d’outil reviennent comme résultat d’outil avec isError: true et le même corps JSON, par exemple {"error":"not_found"} ou {"error":"forbidden","db":"kb"}.

API Erlang

Cycle de vie et documents

RetourSignification et correction
{error, already_exists}create_db sur une base ouverte. Utilisez open_db/1.
{error, invalid_db_name}Lettres minuscules, chiffres, _ et -, de 1 à 63 octets. Un _ en premier est réservé aux bases propres à barrel.
{error, not_found}Un document absent, ou une base qui ne tourne pas.
{error, {db_failed, Reason}}L’écrivain de la base a planté 3 fois en 60 secondes. Corrigez Reason, puis reopen_db/1.
{error, conflict}Un _rev périmé.
{error, read_only}Une écriture sur une base ouverte avec read_only => true.
{error, clock_skew}L’horloge est en retard sur l’écriture la plus récente de la base, ou un HLC distant a été refusé. Corrigez l’horloge.
{error, {invalid_expires_at, V}}expires_at doit être un temps unix positif ou nul en millisecondes.
{error, {invalid_provenance, _}}Champs de provenance trop longs.
{error, {invalid_condition, C}}Une condition find invalide.
{error, db_restarted}Un flux ou un envoi de pièce jointe a survécu à un redémarrage de la base. Rouvrez-le ; l’envoi n’a rien publié.
{error, upload_expired}Un envoi laissé ouvert plus longtemps que att_upload_timeout (3600 s).
{error, {read_only_upgrade_needed, _}}Des magasins qui demandent une mise à niveau, ouverts en lecture seule. Ouvrez une fois en écriture.

BQL

RetourSignification et correction
{error, {parse_error, {Line, Col}, Msg}}Une erreur de syntaxe, depuis barrel_docdb:query/2,3.
{error, {invalid_query, {Line, Col}, Code}}Une instruction que la grammaire accepte mais que le compilateur refuse. Voir BQL.
{error, {table_fn_requires_barrel, Fn}}Les fonctions de table de recherche ne s’exécutent que via barrel:query/2,3.
{error, {unsupported, subscribe}}SUBSCRIBE via query ; utilisez subscribe_query/2,3.
{error, {limit_required, #{max_limit := 1000}}}Une requête de contexte sans LIMIT.

Module barrel

RetourSignification et correction
{error, no_vector_store}Un appel vectoriel, ou un export, sur une base ouverte avec vectordb => none.
{error, record_mode}vector_add sur une base en mode enregistrement ; écrivez plutôt le document.
{error, mixed_batch}Une liste vector_add_batch/2 qui mélange des entrées avec et sans vecteurs.
{error, {invalid_option, vectordb}}embedding avec vectordb => none.
{error, no_stored_policy}embedding => stored sur une base qui n’a jamais tourné en mode enregistrement.
{error, barrel_app_not_started}Le mode enregistrement demande que l’application barrel soit démarrée.
{error, {unknown_options, Keys}}Des clés inconnues dans une politique d’embedding.
{error, {dimension_mismatch, Want, Got}}Un vecteur de mauvaise longueur.
{error, {index_init_failed, faiss_not_available}}backend => faiss sans le NIF barrel_faiss.

Chiffrement

RetourSignification et correction
{error, db_is_encrypted}Passez la spécification de chiffrement à l’ouverture.
{error, wrong_encryption_key}La clé ne correspond pas à cette base.
{error, cannot_encrypt_existing_db}Pas de chiffrement sur place. Créez une base chiffrée et répliquez-y les données.
{error, {key_provider_error, barrel_keyprovider_env, no_encryption_key}}BARREL_ENCRYPTION_KEY n’est pas défini.

Timeline

RetourSignification et correction
{error, not_a_branch}, {error, parent_not_found}Fusion sur une base qui n’est pas une branche, ou dont le parent n’est pas ouvert.
{error, already_exists}, {error, branch_dir_exists}Le nom de branche ou son dossier est déjà pris.
{error, cannot_branch_a_branch}Créez la branche depuis le parent.
{error, pitr_window_exceeded}, {error, {pitr_window_exceeded, DocId}}L’instant, ou l’historique de ce document, est plus ancien que la rétention.
{error, {bad_at, future}}, {error, {bad_at, _}}L’instant est dans le futur, ou n’est pas un HLC valide.

Réplication

RetourSignification et correction
{error, {checkpoint_failed, target, not_found}}La base cible locale n’existe pas. Créez-la d’abord.
{error, not_found}La base distante n’existe pas (HTTP 404).
{error, unauthorized}Le serveur distant a répondu 401.
{error, clock_skew}Le serveur distant a répondu 409 avec {"error":"clock_skew"}. Tout autre 409 revient sous la forme {error, {http, 409, Body}}.
{error, too_large}, {error, {http, Status, Body}}Le serveur distant a répondu 413, ou un autre statut.
{error, {inline_credentials, Keys}}Déplacez les identifiants de la tâche vers sync_auth, sync_signing ou sync_ssl.
{error, att_flush_unsupported}La cible ne sait pas rendre durables les écritures de pièces jointes ; mettez-la à jour ou passez att_durability => best_effort.
{error, {att_flush_failed, R}}, {error, {att_sync_failed, R}}La phase des pièces jointes a échoué ; le checkpoint reste avant elle.
{error, att_filter_unsupported}Le serveur source ne sait pas filtrer les pièces jointes.
{error, too_many_failed_docs}Plus de 1000 documents ont échoué en une exécution ; le checkpoint n’a pas avancé.
{error, not_running}get_task_pid/1 sur une tâche qui ne tourne pas.

Embedding et reclassement

RetourSignification et correction
{error, embedder_not_configured}Pas d’embedder dans la configuration.
{error, no_providers_available}Aucun fournisseur de la chaîne n’a pu démarrer.
{error, all_providers_failed}Tous les fournisseurs ont échoué sur cet appel.
{error, venv_not_found}Le venv Python géré est absent.
{error, {port_open_failed, enoent}}barrel_rerank n’a pas pu lancer Python ; passez un python absolu.

Espaces et capacités

RetourSignification et correction
{error, invalid_token}Token inconnu ou altéré.
{error, revoked}Révoqué, ou token de passation après complete.
{error, expired}expires_at est dépassé.
{error, wrong_space}Un token pour un autre espace (403 en REST).
{error, forbidden}Le droit n’est pas accordé (read, puis write, puis admin).
{error, space_dropped}L’espace a été supprimé.
{error, already_accepted}, {error, already_completed}La passation a déjà été utilisée.
{error, {embedder_mismatch, _}}, {error, {embedder_required, _}}open_space avec un embedder différent de celui de l’espace, ou sans embedder alors que l’espace en demande un.

Pièces jointes S3

RetourSignification et correction
{error, {att_store_open_failed, missing_bucket}}att_opts sans bucket. Le bucket doit exister.
{error, {conflict, Info}}Une écriture create_only ou expected_etag a perdu.
{error, conditional_writes_unsupported}Le magasin ne sait pas faire d’écritures conditionnelles.
{error, {att_sync_pending, _}}Une nouvelle branche copie encore ses pièces jointes.

Traduit de la page anglaise: /docs/reference/errors/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir