Dépannage
Cette page liste les symptômes que vous pouvez rencontrer, leur cause et leur correction. Cherchez votre erreur avec le champ de recherche, ou parcourez le domaine dont elle vient. Pour la signification de chaque code d’erreur pris isolément, voir Codes d’erreur.
Horloges
| Symptôme | Cause | Correction |
|---|---|---|
Les écritures échouent avec {error, clock_skew} après un redémarrage | L’horloge du nœud est revenue en dessous de l’écriture la plus récente faite par la base. Les données sont conservées et l’écrivain reste actif. | Corrigez l’horloge (NTP). Les écritures reprennent dès qu’elle dépasse ce point. |
La réplication depuis un pair échoue avec clock_skew | L’horloge du pair est en avance de plus de hlc_max_offset millisecondes. En HTTP, une réponse 409 n’est signalée comme clock_skew que si son corps indique {"error":"clock_skew"}. | Synchronisez les horloges. |
La réplication en HTTP échoue avec {error, {http, 409, Body}} | Le pair, ou un proxy placé devant lui, a répondu 409 pour une autre raison. | Lisez Body. |
hlc_max_offset vaut 0 par défaut, ce qui désactive la vérification du décalage. Définissez-le dans l’environnement applicatif de barrel_docdb uniquement si vous voulez refuser les pairs dont l’horloge dérive.
Réplication
| Symptôme | Cause | Correction |
|---|---|---|
replicate renvoie {error, not_found} contre un serveur | La base distante n’existe pas. La réplication n’en crée jamais. | Faites d’abord PUT /db/:db sur le serveur distant. |
{error, {checkpoint_failed, target, not_found}} sur un seul nœud | La base cible locale n’a pas été créée. | Appelez d’abord barrel_docdb:create_db(Target). |
{error, att_flush_unsupported} | La cible ne peut pas confirmer que les pièces jointes sont sur le disque, et la durabilité est exigée par défaut. | Mettez la cible à jour, ou passez att_durability => best_effort en acceptant le risque en cas de coupure de courant. |
{error, att_filter_unsupported} sur une exécution filtrée | Le serveur source ne sait pas filtrer les pièces jointes. | Mettez la source à jour. |
start_task renvoie {error, {inline_credentials, Keys}} | Les tâches refusent les identifiants dans leur configuration. | Définissez sync_auth, sync_signing ou sync_ssl dans l’environnement applicatif de barrel_docdb. |
Une tâche continue affiche running mais rien n’arrive | Elle réessaie ; l’erreur est stockée dans last_error. | Lisez barrel_rep_tasks:get_task(Id) et corrigez last_error. |
Une tâche est paused avec db_closed | Sa base locale n’est pas ouverte. | Ouvrez la base, ou définissez task_db_opener pour que les tâches restaurées l’ouvrent. |
{error, too_many_failed_docs} | Plus de 1000 documents ont échoué en une exécution ; le checkpoint n’a pas avancé. | Cherchez les documents en échec dans le log et corrigez-les, puis relancez. |
| Après une mise à jour depuis docdb 2.0, une réplique manque de documents ou contient des corps vides | Bugs de la 2.0.0. La mise à jour arrête les nouveaux dégâts mais ne répare rien. | Lancez barrel_rep:reconcile(Healthy, Replica, #{}) une fois par réplique. |
{ok, Report} = barrel_rep:reconcile(<<"kb">>,
<<"kb_replica">>, #{}),
maps:with([docs_checked, bodies_repaired,
atts_resent], Report).
Recherche
| Symptôme | Cause | Correction |
|---|---|---|
500 bm25_not_enabled | La recherche par mots-clés est désactivée sur une base simple. | Ouvrez avec vectordb => #{bm25_backend => disk}, ou utilisez le mode enregistrement, qui l’active. |
500 embedder_not_configured | Recherche texte ou hybride sans embedder. | Configurez un embedder, ou envoyez un vecteur. |
500 {dimension_mismatch,768,N} | Le magasin attend 768 dimensions par défaut. | Envoyez des vecteurs à la taille du magasin, ou ouvrez-le avec les dimensions du modèle. |
| Les vecteurs n’ont pas la bonne longueur | dimensions n’est pas défini et vaut 768 par défaut. | Réglez dimensions sur la taille du modèle (384 pour bge-small). |
| Le premier embedding local est lent ou échoue hors ligne | Les fournisseurs Python installent des paquets et téléchargent le modèle à la première utilisation. | Faites un premier passage en ligne, puis exécutez avec HF_HUB_OFFLINE=1 et TRANSFORMERS_OFFLINE=1. |
barrel_vectordb:update/4 ou upsert a fait disparaître une entrée | Un bug antérieur à barrel_vectordb 2.5.3 : l’entrée était supprimée avant que le nouveau texte soit transformé en embedding, si bien qu’un échec du calcul la perdait. | Passez à barrel_vectordb 2.5.3. Un échec du calcul garde alors l’ancienne entrée et renvoie l’erreur. |
Bases et serveur
| Symptôme | Cause | Correction |
|---|---|---|
open_db renvoie {error, {db_failed, Reason}} | L’écrivain a planté 3 fois en 60 secondes. Cette base reste arrêtée ; les autres ne sont pas touchées. | Cherchez Reason dans le log, corrigez, puis barrel_docdb:reopen_db(Name). |
{error, db_is_encrypted} | Ouverte sans ses paramètres de chiffrement. | Passez la même spécification encryption à chaque ouverture. |
L’ouverture échoue avec Snappy is not available | barrel_docdb 2.2.0 compressait avec Snappy, et rocksdb a été compilé sans la bibliothèque Snappy du système. | Passez à barrel_docdb 2.2.1, qui utilise zstd. Ou installez libsnappy-dev (ou le paquet Snappy de votre système) et recompilez rocksdb. |
Un appel REST répond 404 db_not_found | La base n’existe pas. Depuis barrel_server 1.14.0, seul PUT /db/:db en crée une ; avant, n’importe quelle route le faisait, si bien qu’une faute de frappe laissait une base vide. | Vérifiez le nom, ou créez d’abord la base avec PUT /db/:db. DELETE /db/:db?purge=true supprime une base vide laissée par un serveur plus ancien. |
PUT /db/MyDb répond 400 invalid_name | Les noms de base utilisent des lettres minuscules, des chiffres, _ et -, de 1 à 63 octets, et ne commencent pas par _. Avant barrel_server 1.14.0, la réponse était 500 invalid_db_name. | Utilisez un nom conforme à cette règle. |
Des fichiers de vecteurs apparaissent dans ./priv | Le magasin de vecteurs a été créé avant barrel 1.13.0 sans db_path, sous le répertoire de travail. Il continue d’y être utilisé, avec une notice dans le journal ; les nouveaux magasins vont dans <data_dir>/<name>.vectordb. | Sauvegardez ce dossier, ou définissez vectordb => #{db_path => ...} pour le placer vous-même. |
| Un jeton de capacité reçoit 403 | Il est pour un autre espace, ou n’a pas le droit nécessaire. | Utilisez un jeton pour cet espace avec le droit requis. |
Prometheus ne trouve rien sur /metrics | Cette route n’existe pas. | Poussez avec l’exporter OTLP, voir Supervision. |
barrel_db_documents_total_db manque juste après une mise à jour | Une base écrite avant barrel_docdb 2.4.0 est comptée une fois en arrière-plan après son ouverture. | Attendez le premier comptage ; db_info renvoie documents à undefined d’ici là. |
barrel_db_pending_compaction_bytes_db ne cesse de grandir | La compaction ne suit plus les écritures. | Augmentez max_background_jobs dans store_opts, ou étalez les écritures. |
Un avertissement dit que compaction_interval ou prune_depth n’a plus d’effet | Ces options ont été retirées dans barrel_docdb 2.2.0. | Retirez-les de votre configuration. |
Branches
| Symptôme | Cause | Correction |
|---|---|---|
400 pitr_window_exceeded | L’instant est plus ancien que l’historique conservé (30 jours par défaut). | Choisissez un instant plus récent, ou augmentez retention_period. |
409 cannot_branch_a_branch | La lignée n’a qu’un niveau. | Créez la branche depuis le parent. |
Utilitaires Python
| Symptôme | Cause | Correction |
|---|---|---|
barrel_rerank crée un venv dans un dossier nommé undefined | Un bug de barrel_rerank 1.0.2 : l’application déclare venv_path à undefined et le code l’utilisait comme chemin. | Passez à barrel_rerank 1.0.3, qui utilise priv/.venv quand venv_path n’est pas défini. Supprimez le dossier undefined. |
barrel_rerank:start_link/1 renvoie {error, {port_open_failed, enoent}} | python n’est pas un chemin absolu et l’installation du venv a échoué. | Passez un python absolu, ou un venv_path fonctionnel. |
Si votre symptôme n’est pas ici, cherchez l’erreur dans Codes d’erreur, puis consultez le log du nœud pour le terme de la raison.