# Dépannage

> Solutions aux problèmes courants : commande ducklocal introuvable, fichiers non attachés, bases qui ne s’ouvrent pas, requêtes bloquées, S3.

Source: https://ducklocal.app/docs/fr/troubleshooting

Trouvez le symptôme, lisez la cause, appliquez le correctif. Si votre problème
n'est pas listé, [ouvrez un ticket](https://github.com/JetSquirrel/DuckLocal/issues) avec le détail de ce que vous avez fait et de ce qui s'est passé.

## Installation et lancement

| Symptôme | Cause et correctif |
| --- | --- |
| L'application ne s'ouvre pas sur un Mac Intel | La version macOS est compilée pour Apple silicon uniquement. [Compilez depuis les sources](development.md#build-and-run) sur Intel |
| Les raccourcis de cette documentation ne font rien sous Windows ou Linux | Lisez **Ctrl** à la place de **⌘** : ⌘↵ correspond à Ctrl+Enter |
| `ducklocal: command not found` | L'image disque installe l'application, pas une commande. [Liez le binaire dans votre PATH](getting-started.md#add-command) |
| Le terminal reste occupé tant que la fenêtre est ouverte | Lancer l'interface graphique depuis un terminal l'exécute au premier plan. Lancez-la plutôt depuis Applications, ou laissez ce terminal s'en occuper |
| L'historique, les paramètres ou les fichiers mémorisés cessent d'être enregistrés | Un second DuckLocal est en cours d'exécution et garde le fichier de données de l'application. Quittez l'autre et relancez |
| **DuckLocal s'est arrêté de façon inattendue la dernière fois** | Il a planté et enregistré un rapport dans le dossier des journaux. Cliquez sur **Afficher le rapport** et joignez-le à un [ticket](https://github.com/JetSquirrel/DuckLocal/issues) — voir [où les données sont stockées](settings-and-data.md#where-things-are-stored) |
| **Échec de la recherche de mise à jour** | Survolez-la pour connaître la raison : hors ligne, un proxy, ou un téléchargement dont la somme de contrôle ne correspond pas. Cliquez pour réessayer, ou téléchargez la version depuis GitHub — voir [Recherche de mise à jour](settings-and-data.md#update-check) |

## Ouverture des données

| Symptôme | Cause et correctif |
| --- | --- |
| `File not found` sur un chemin que vous avez indiqué | Le chemin n'existe pas, ou est relatif à un autre dossier que vous ne le pensez. Utilisez un chemin absolu pour être sûr |
| Un dossier ne signale aucun fichier de données | Rien en dessous ne correspond à `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb` ou `.ods` |
| Un dossier a produit moins de fichiers que prévu | Les entrées masquées et les liens symboliques sont ignorés, et une demande d'ouverture attache au plus 256 fichiers. Ouvrez les sous-dossiers séparément |
| Un chemin s'est ouvert comme base de données alors qu'il ne fallait pas | Tout fichier existant qui n'est pas un fichier de données est traité comme une base DuckDB. S'il ne s'ouvre pas, DuckLocal en donne la raison ; au lancement, il se rabat sur la mémoire. Voir [Ouvrir une base de données](#opening-a-database) |
| **Non attaché … : la base de données contient déjà une table ou une vue nommée …** | La base contient déjà une table ou une vue du même nom que le fichier mémorisé. DuckLocal ne la remplace jamais. Renommez ou supprimez l'une des deux, ou retirez le fichier de **Fichiers locaux** et rouvrez-le pour obtenir un nouveau nom |
| **Impossible de restaurer le chemin relatif …** | Un fichier a été mémorisé par un chemin relatif, qui ne peut pas être résolu dans une nouvelle session. Retirez-le de **Fichiers locaux** et rouvrez-le |
| Une vue affiche `sales_2` au lieu de `sales` | Un autre fichier ou une autre table portait déjà ce nom, la nouvelle vue a donc reçu un suffixe |
| La vue d'un fichier est obsolète | Les vues lisent le fichier à chaque requête. Si la forme des colonnes d'un CSV a changé, utilisez **Actualiser le schéma** dans la barre latérale |

## Ouvrir une base de données {#opening-a-database}

| Symptôme | Cause et correctif |
| --- | --- |
| Le message dit que la base a été créée par un DuckDB plus récent | Le fichier utilise un format de stockage plus récent que ce que le DuckDB intégré à DuckLocal sait lire. Exécutez les lignes `ATTACH … COPY FROM DATABASE` du message dans le DuckDB qui a créé le fichier, puis ouvrez la copie. Voir [Quand une base de données ne s'ouvre pas](data-sources.md#when-a-database-will-not-open) |
| Le message dit que la base vient de DuckDB v0.9 ou antérieur | Exécutez `EXPORT DATABASE 'dir'` avec le DuckDB qui l'a écrite, puis `IMPORT DATABASE 'dir'` dans DuckLocal |
| Le message dit qu'il s'agit d'une base SQLite | Attachez-la avec **Ouvrir → Attacher une base de données…** au lieu de l'ouvrir |
| Le message dit que le fichier n'est pas une base DuckDB | Son extension n'est pas une de celles que DuckLocal lit comme données, il a donc été essayé comme base. Donnez-lui une [extension prise en charge](data-sources.md#supported-file-formats), ou lisez-le en SQL, par exemple `SELECT * FROM read_csv('export.dat')` |
| DuckDB dit qu'il n'a pas pu poser un verrou sur le fichier | Un autre programme — un autre DuckDB, un script, une seconde application — a la base ouverte en écriture, et DuckDB ne laisse qu'un seul processus écrire dans un fichier. Fermez-la dans cet autre programme, puis rouvrez le fichier |
| DuckDB signale un accès refusé | Votre compte ne peut pas lire le fichier, ou pas y écrire : la base principale est ouverte en écriture. Corrigez les permissions du fichier, ou attachez-le avec **Lecture seule** cochée |
| Une ouverture de base a échoué et rien n'a changé | C'est attendu tant que DuckLocal est en cours d'exécution : une ouverture ratée laisse l'espace de travail que vous aviez. Lisez la notification pour connaître la raison |
| L'infobulle de la barre d'état indique **lisible par DuckDB v1.x+** et un collègue ne peut pas ouvrir le fichier | Son DuckDB est plus ancien que cette version. Il doit mettre à jour, ou vous copiez le fichier avec un `STORAGE_VERSION` plus ancien — voir [Quel DuckDB peut lire une base de données](data-sources.md#storage-version) |

## Bases de données attachées

| Symptôme | Cause et correctif |
| --- | --- |
| Une base attachée a disparu après un relancement | Son fichier n'était pas au chemin mémorisé au lancement, elle a donc été ignorée. L'enregistrement est conservé ; remettez le fichier en place et elle reviendra à la prochaine connexion |
| **Cette base de données est déjà ouverte, sous le nom …** | Le fichier est déjà la base principale, ou est attaché sous ce nom. Interrogez-le par ce nom |
| **Impossible d'attacher … : le nom … est déjà pris dans la base ouverte.** | Quelque chose d'autre dans la connexion utilise déjà l'alias mémorisé — par exemple une base que vous avez attachée en SQL sous le même nom. Détachez celle-là avec `DETACH`, puis rouvrez la base ou relancez |
| L'écriture dans une base attachée échoue | Elle a été attachée en lecture seule, le comportement par défaut. Utilisez **Détacher la base de données** dans la barre latérale, puis attachez-la à nouveau avec **Lecture seule** décochée |
| L'attachement a créé une base vide | Avec **Lecture seule** décochée, un chemin DuckDB qui n'existe pas est créé. Détachez-la, supprimez le fichier vide et vérifiez le chemin |
| Un nom de table sans base trouve la mauvaise table | Les noms sans base se résolvent dans la base par défaut. Faites un clic droit sur une base et choisissez **Utiliser comme base par défaut**, ou écrivez `alias.table` |

## Finder et Quick Look

Ces fonctions sont réservées à macOS.

| Symptôme | Cause et correctif |
| --- | --- |
| Un double-clic sur un fichier `.parquet` ou `.duckdb` ouvre une autre application | Cette application est déjà celle par défaut. Dans le Finder, **Lire les informations → Ouvrir avec**, choisissez DuckLocal, puis **Tout modifier…** |
| Un double-clic sur un fichier CSV ou Excel n'ouvre pas DuckLocal | C'est voulu : DuckLocal ne prend pas ces formats en charge. Utilisez **Ouvrir avec → DuckLocal**, ou déposez le fichier sur l'icône du Dock |
| DuckLocal n'est pas proposé dans **Ouvrir avec**, ou Espace n'affiche aucun aperçu DuckLocal | macOS n'a pas encore enregistré l'application. Déplacez-la dans Applications et lancez-la une fois. Pour l'aperçu, exécutez ensuite `qlmanage -r` dans le Terminal, et vérifiez que **Aperçu DuckLocal** est activé dans Quick Look, dans les réglages d'extensions des Réglages Système |
| Un fichier `.json` ordinaire ou un fichier Excel n'affiche aucun aperçu DuckLocal | C'est voulu : ils sont laissés aux aperçus de macOS. Les fichiers `.jsonl` et `.ndjson` sont prévisualisés |
| L'aperçu n'affiche que 50 lignes | C'est voulu : un aperçu ne parcourt jamais le fichier entier. Ouvrez le fichier dans DuckLocal pour le reste |
| L'aperçu d'un fichier `.duckdb` affiche une erreur | L'aperçu lit le fichier avec le DuckDB de DuckLocal, un fichier issu d'un DuckDB plus récent échoue donc là aussi. Voir [Ouvrir une base de données](#opening-a-database) |

## Exécution des requêtes

| Symptôme | Cause et correctif |
| --- | --- |
| **Exécuter** ne fait rien | Une requête est déjà en cours. Cliquez sur **Arrêter** à côté d'Exécuter, ou sur **⌘.**, pour l'interrompre |
| Une requête a échoué avec `Interrupted` | Quelqu'un a appuyé sur **Arrêter** (ou ⌘.) pendant son exécution. Relancez-la |
| Une partie de mon SQL est soulignée d'un trait ondulé rouge | La dernière exécution a échoué à cet endroit. Lisez le message *Échec de la requête* ; la marque disparaît à l'exécution suivante |
| **⌘↵** affiche l'éditeur au lieu d'exécuter | Sur l'écran de premier lancement, ⌘↵ signifie « donnez-moi un éditeur ». Appuyez à nouveau pour exécuter |
| Les résultats s'arrêtent tôt avec un avis de troncature | Le plafond de 100 000 lignes ou de 2 000 000 de cellules a été atteint. Restreignez la requête ; il n'y a pas de pagination |
| Les horodatages semblent décalés | La grille affiche les horodatages en UTC, pas en heure locale |
| Une valeur `TIMETZ` a perdu son décalage, ou une valeur `BIT` ou `BIGNUM` ressemble à des octets | Ces types ne peuvent pas être distingués des valeurs ordinaires à l'arrivée dans DuckLocal. `CAST(column AS VARCHAR)` en SQL affiche la vraie valeur |
| Le tri ne fait pas venir les lignes au-delà de l'aperçu | Le tri par en-tête ne réordonne que les lignes chargées. Utilisez `ORDER BY` en SQL pour ordonner le résultat complet avant troncature |
| Une requête a besoin d'une extension non installée | Les extensions manquantes ne sont plus téléchargées automatiquement. Installez-la explicitement dans l'onglet **Extensions**, puis chargez-la ou relancez la requête |
| Une requête qui fonctionnait avant 0.3.0 dit qu'une extension n'est pas installée, ou qu'une fonction n'existe pas | DuckLocal 0.3.0 exécute DuckDB 2.0, qui conserve les extensions installées par version. Installez-les à nouveau depuis l'onglet **Extensions** — voir [Extensions](schema-and-history.md#extensions) |
| Un alias de colonne nu comme `minutes` provoque une erreur d'analyseur | C'est un mot-clé SQL. Écrivez `AS minutes`, ou mettez-le entre guillemets : `SELECT count(*) AS "minutes" FROM events` |
| Cliquer sur une table ou une entrée d'historique a effacé mon SQL | Ces clics remplacent tout le contenu de l'éditeur. Utilisez un nouvel onglet de requête pour vos essais |
| Un export a remplacé un fichier sans prévenir | L'export écrit au chemin indiqué sans demander. Choisissez un nouveau nom |

## S3

| Symptôme | Cause et correctif |
| --- | --- |
| Les identifiants S3 ont été oubliés | Ils ne durent que le temps de la session, c'est voulu, et ouvrir ou changer de base de données les efface. Reconfigurez S3 |
| La configuration de S3 échoue hors ligne | Le premier usage lance `INSTALL httpfs`, qui télécharge l'extension. Connectez-vous une fois, elle est ensuite en cache |
| Les identifiants temporaires (STS) sont refusés | Aucun jeton de session n'est envoyé. Utilisez des clés de longue durée — voir [S3 et httpfs](s3.md#limitations) |
| Un bucket semble plus petit qu'il ne l'est | Le listage s'arrête à 1 000 entrées par niveau. Interrogez plutôt avec un motif comme `'s3://bucket/prefix/*.parquet'` |

## Tableaux de bord

| Symptôme | Cause et correctif |
| --- | --- |
| Un graphique de tableau de bord dit qu'une requête doit être en lecture seule | Une requête du `.dash` a tenté d'écrire (DDL, DML, `COPY`, `ATTACH`, …). Les tableaux de bord n'exécutent que des instructions en lecture seule ; déplacez la préparation dans l'éditeur SQL |
| Un agent n'a pas vu mes commentaires | Les commentaires ne sont envoyés nulle part : l'agent doit les lire. Demandez-lui d'exécuter `ducklocal comments FILE`, ou de « traiter les commentaires de FILE » s'il a la [compétence officielle](cli.md#install-the-official-skill) |
| La réponse ou la modification d'un agent ne s'affiche pas | La fenêtre suit à la fois la spécification et `FILE.comments.json` en moins d'une seconde. Une spécification qui ne valide plus laisse le dernier tableau de bord fonctionnel affiché, avec la raison au-dessus ; ouvrez **Voir la spécification** pour voir le fichier |
| Un `PIVOT` dans un tableau de bord est refusé | Un `PIVOT` imbriqué dans un `SELECT` ou un `WITH` doit nommer ses valeurs. Listez-les : `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`, ou commencez la requête par le `PIVOT` |

## Apparence

| Symptôme | Cause et correctif |
| --- | --- |
| Le thème revient au clair à chaque lancement | Le thème n'est pas enregistré entre les lancements ; la langue, elle, l'est |
| Le texte ou les icônes sont trop petits ou trop grands | Utilisez le bouton **Aa** de la barre de titre, ou ⌘+ / ⌘− / ⌘0. Voir [Taille de l'interface](settings-and-data.md#interface-size) |
| L'interface est dans la mauvaise langue | Utilisez le bouton `EN` / `中` de la barre de titre ; le choix est mémorisé |

## Repartir de zéro

Pour effacer l'historique, les fichiers mémorisés, les onglets ouverts et les
paramètres, quittez DuckLocal et supprimez son dossier de données
d'application :

```bash
rm -rf ~/Library/Application\ Support/DuckLocal
```

Vos fichiers de données ne sont jamais touchés — seuls les enregistrements
propres à DuckLocal sont supprimés. Voir [Paramètres et données de
l'application](settings-and-data.md) pour savoir ce qui y est stocké.
