9. Aide

9.1 Quand quelque chose ne va pas

Sur un nouveau PC, d'abord la « Santé du kit ». Puis les problèmes les plus courants, le message que vous voyez et quoi faire : téléchargements, ports occupés, serveurs qui ne démarrent pas, connexions expirées. Et comment signaler un problème avec le zip du diagnostic.

En bref

  • Cherchez le message que vous voyez dans le champ ci-dessous : le guide rassemble les plus courants, avec la solution.
  • Presque chaque erreur a une info-bulle au survol de la souris et une ligne de sortie ou de journal qui en dit plus.
  • Le journal de l'application est dans data\app\logs\app.log ; ceux des serveurs à côté.

Santé du kit

Sur un nouveau PC, ou avec le kit sur une autre clé, regardez d'abord Paramètres › « Le kit » › « Santé du kit » : une ligne par contrôle, verte si tout va bien, jaune pour un avertissement, rouge pour une erreur, et en dessous ce qu'il faut faire. « Vérifier à nouveau » refait les contrôles après une correction.

  • Le disque. FAT32 accepte des fichiers jusqu'à 4 Go (pas de grands modèles locaux ni de grandes copies de bases de données) et aucun lien : pour un kit sur clé, exFAT est préférable, ou NTFS s'il reste sous Windows. Sous macOS et Linux, un disque monté noexec (ou FAT32 avec showexec sous Linux) ne laisse démarrer aucun programme : la ligne donne la commande pour le remonter.
  • L'espace libre : sous 5 Go un avertissement, sous 1 Go une erreur (installations, téléchargements et copies des bases de données échouent). Libérez de l'espace ou déplacez le kit sur un disque plus grand.
  • Le chemin du kit : &, %, !, ^, les apostrophes et guillemets, les lettres accentuées ou hors de l'alphabet latin perturbent cmd, PowerShell, Maven et Gradle. Déplacez le kit dans un dossier avec seulement des lettres, des chiffres, des tirets et des espaces.
  • Des fichiers rendus privés par un autre compte, souvent sur un autre PC : le kit ne peut pas les lire (paramètres, clés, connexions des agents). La ligne donne la commande pour les récupérer, à lancer dans un terminal administrateur : takeown et icacls sous Windows, sudo chown sous macOS et Linux. L'application ne la lance pas elle-même car il faut les droits d'administrateur.
  • Sous Linux, les bibliothèques du système : libaio et libnuma pour MySQL, libicu pour .NET, libvulkan1 pour la carte graphique des modèles locaux (sans elle, ils restent sur le CPU). La ligne donne la commande pour les installer, par exemple avec apt.
  • En ligne de commande, .\Atollo.exe check --kit | Out-Host fait les mêmes contrôles, et se termine par 1 si l'un d'eux est une erreur.

Téléchargement et installation

Un composant reste en « erreur » avec « échec » et un message de réseau ou de certificat.

C'est souvent le réseau : un proxy d'entreprise ou l'inspection HTTPS. Remplissez Paramètres › Réseau et réessayez. Si cela ne suffit pas, utilisez le panneau « Téléchargez-le dans le navigateur » sous la ligne et remettez le fichier au kit.

En savoir plus : Réseau d'entreprise : proxy, certificats, réseau local (6.3)

« en cours d'utilisation : fermez les programmes du kit et réessayez »

Un programme du kit (un projet lancé, une console, l'éditeur, une base de données) utilise les fichiers à remplacer. Arrêtez-le, fermez les consoles et réessayez. Si vous ne savez pas ce qui est ouvert, la page « Retirer le lecteur » le liste.

En savoir plus : Retirer le lecteur en toute sécurité (7.1)

« Une installation est déjà en cours. » ou « Une installation est déjà en cours »

Attendez qu'elle se termine (la barre d'état affiche l'étape) ou appuyez sur « Annuler » dans la barre « Appliquer ».

Un composant est « à mettre à jour » (triangle jaune).

Sur macOS et Linux, après un déplacement du kit, certains composants doivent être réinstallés : le kit le fait tout seul au démarrage. Si cela reste ainsi, appuyez sur « Tout mettre à jour » en bas de la page Outils.

En savoir plus : Sur un autre PC, une autre lettre, un autre dossier (7.2)

Un programme plante ou une bibliothèque manque, avec le kit sur une clé USB.

Un fichier du programme peut s'être endommagé sur la clé. Appuyez sur « Vérifier les fichiers » dans la page Outils (ou lancez check --files) : la liste montre les dossiers avec des fichiers manquants ou modifiés depuis l'installation, et « Réinstaller » les remet à la même version, sans toucher aux projets ni aux bases de données.

En savoir plus : La page Outils (5.1)

Projets et sites

« Port déjà attribué à … », « Le port … appartient déjà au serveur/à la base de données/au projet … : choisissez-en un autre. », « Les ports 7000 à 7099 sont réservés à l'éditeur » ou un programme qui dit que le port est occupé.

Un port n'appartient qu'à une seule chose : une action d'un projet, un pool de la page Serveurs web, une version d'une base de données ou l'éditeur (7000-7099). Le message dit qui l'a déjà : « Port déjà attribué à … » une autre action, « appartient déjà au serveur … » un pool, « appartient déjà à la base de données … » une version de MySQL ou MongoDB, « appartient déjà au projet … » une action. Cela vaut pour le port d'une action, d'un pool et d'une version de la base de données. Si c'est un programme du PC qui a le port, c'est ce programme qui le dit. Pour une action, videz le champ « Port » pour revenir au port automatique ; sinon choisissez-en un autre entre 1024 et 65535.

En savoir plus : Démarrer un projet : actions et ports (2.3)

Une action s'arrête tout de suite avec « erreur (code 1) ».

Lisez les dernières lignes de la sortie : elles disent généralement ce qui manque. Cas fréquents : dépendances non installées (exécutez d'abord npm install ou composer install), un composant manquant (section « Composants » › « Installer ce qui manque »), une mauvaise version (section « Versions »).

En savoir plus : Composants et versions d'un projet (2.4)

« Action introuvable : cliquez sur Actualiser »

Le projet a changé (par exemple panel.json). Appuyez sur « Actualiser » dans la page du projet.

« panel.json n'est pas un JSON valide : ignoré. »

Il y a une erreur de syntaxe dans le fichier (une virgule en trop, un guillemet manquant). Corrigez-la dans l'éditeur et appuyez sur « Actualiser ».

En savoir plus : Démarrer un projet : actions et ports (2.3)

« Le serveur partagé … n'a pas démarré : voyez la page Serveurs web. »

Ouvrez la page Serveurs web, choisissez le pool et regardez l'erreur. Souvent le port est occupé : changez le port du profil, ou choisissez « Son propre serveur » dans la section « Site web » du projet.

En savoir plus : Sites web et adresses .localhost (3.3)

Le site s'ouvre mais affiche d'anciens fichiers ou une page blanche.

Vérifiez le dossier dans « Dossier à servir comme site web » (pour beaucoup de frameworks PHP, c'est public) et rechargez la page du navigateur en ignorant le cache (Ctrl+F5).

L'éditeur ne s'aperçoit pas des fichiers modifiés.

Sur Windows, cela arrive si un dossier du chemin du kit commence par un chiffre, par x ou par u : l'application le signale par un avertissement. Déplacez le kit vers un autre chemin.

En savoir plus : Le premier lancement (1.2)

Bases de données

« Le port … est déjà utilisé par un autre programme : changez-le ci-dessous. »

Un autre MySQL ou MongoDB (installé à part) tourne sur le PC sur le même port. Changez le « Port » dans la page du serveur (par exemple 3307) et démarrez-le de nouveau ; puis réécrivez la connexion dans le .env des projets avec « Écrire dans .env ».

En savoir plus : Les serveurs de bases de données (3.1)

Le serveur reste en « Erreur » après le démarrage.

La page du serveur affiche la dernière erreur et le chemin du journal (data\app\logs). Sur Linux, MySQL peut demander les bibliothèques libaio et libnuma : le message indique la commande pour les installer.

Le projet ne se connecte pas à la base de données.

Vérifiez que le serveur est « Démarré », puis utilisez « Écrire dans .env » dans la section « Bases de données » du projet : le .env aura l'utilisateur, le mot de passe et le port corrects. Si le projet utilise une autre version du serveur, le port est différent (3307…).

En savoir plus : La base de données d'un projet (3.2)

Agents, Git et GitHub

« connexion expirée » dans les agents.

Ouvrez l'agent dans un projet : il renouvelle la connexion, ou vous la fait refaire.

En savoir plus : Les agents : Claude Code, Codex, Antigravity, Pi (4.1)

Git dit « Please tell me who you are » au premier commit.

Saisissez votre nom et votre e-mail dans Paramètres › « Compte GitHub » › « Qui signe les commits », ou connectez-vous à GitHub : s'ils sont vides, le compte les remplit. Dans un terminal du kit, git config --global user.name et user.email fonctionnent aussi.

En savoir plus : Le compte GitHub du kit (6.1)

« GitHub a refusé la connexion : connectez-vous de nouveau. »

Le jeton n'est plus valide (révoqué ou expiré). Dans Paramètres › « Compte GitHub », appuyez sur « Se déconnecter » puis sur « Se connecter à GitHub ».

En savoir plus : Le compte GitHub du kit (6.1)

Démarrage de l'application

« Le disque du kit est en lecture seule : impossible d'écrire dans le dossier … »

La clé USB est protégée en écriture (il y a parfois un interrupteur) ou montée en lecture seule. Le kit doit pouvoir écrire dans son dossier.

macOS : « macOS a ouvert Atollo depuis une copie temporaire en lecture seule (App Translocation) ».

Cela arrive avec les applications téléchargées et non notarisées. Le message affiche une commande xattr : exécutez-la dans le Terminal et rouvrez Atollo.

En savoir plus : Sur un autre PC, une autre lettre, un autre dossier (7.2)

Linux : le disque est monté avec noexec, ou WebKitGTK manque.

Le message explique quoi faire : remontez le disque avec la permission d'exécution, ou installez les paquets indiqués.

Windows : WebView2 manque.

WebView2 est le composant de Windows qui dessine la fenêtre ; il est déjà présent dans Windows 11 et presque toujours dans Windows 10. S'il manque, Atollo affiche le lien pour l'installer.

Avertissement : « Des programmes d'une autre copie du kit sont ouverts sur ce PC ».

Simple information : un autre kit est ouvert. Les deux copies ne partagent rien.

Si le problème n'est pas ici

  • Lisez la sortie de l'action (section « Lancement ») ou le journal du serveur : la dernière ligne donne généralement la cause.
  • Fermez Atollo et rouvrez-le : beaucoup de choses (environnement, agents, fichiers du kit) sont régénérées à chaque démarrage.
  • Contrôlez les composants avec « Vérifier » dans la page Outils, ou avec .\Atollo.exe check | Out-Host.
  • Si cela ne marche toujours pas, signalez-le : la section ci-dessous explique comment.

Signaler un problème

Dans Paramètres › « Le kit » › « Signaler un problème », il y a deux boutons, à utiliser dans cet ordre.

  • « Exporter le diagnostic » crée sur le PC le zip atollo-diagnostica-<date-heure>.zip dans data\app\diagnostics : version et système, disque du kit (système de fichiers, type, espace libre), RAM, environnement du kit, la vérification des programmes, les composants, les ports et la fin de chaque journal. « Ouvrir le dossier » l'affiche. En ligne de commande, .\Atollo.exe diagnostics | Out-Host fait la même chose.
  • Avant l'écriture du zip, chaque secret que le kit conserve (les clés de data\app\secrets, le jeton de Claude Code, les mots de passe des bases de données, les connexions des agents, le jeton GitHub) devient *** partout où il apparaît ; le dossier de votre profil devient ~, votre nom d'utilisateur et le nom du PC ***. Ouvrez-le et regardez-le quand même avant de le joindre : un projet peut écrire dans les journaux des choses que le kit ne connaît pas.
  • « Signaler un problème » ouvre dans le navigateur une nouvelle issue sur github.com/nabre/atollo avec le formulaire des problèmes : la version d'Atollo et le système (kit, build de Windows, système de fichiers et type du disque) sont déjà remplis. Racontez ce qui s'est passé et les étapes pour le reproduire, et faites glisser le zip dans l'issue.
  • L'application n'envoie rien : le zip reste sur le PC tant que vous ne le joignez pas, et l'issue n'arrive à GitHub que lorsque vous appuyez sur « Create » (il faut un compte GitHub). À partir de là, les règles de confidentialité de GitHub s'appliquent, et l'issue est publique.