# 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](/fr/docs/reference/errors).

## 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. |

```erlang
{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](/fr/docs/operate/monitoring). |
| `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. |

> **Remarque:** Si votre symptôme n’est pas ici, cherchez l’erreur dans [Codes d’erreur](/fr/docs/reference/errors), puis consultez le log du nœud pour le terme de la raison.
