Dépannage
Trouvez le symptôme, lisez la cause, appliquez le correctif. Si votre problème n'est pas listé, ouvrez un ticket 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 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 |
| 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 — voir où les données sont stockées |
| É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 |
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 |
| 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
| 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 |
| 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, 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 |
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 |
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 |
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 |
| 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 |
| 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 |
| 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/DuckLocalVos 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 pour savoir ce qui y est stocké.
