claude-cluster docs1.10.1
User guideGuide utilisateur

TroubleshootingDépannage

The usual problems and where to look: build, window, web access, certificates, voice, phone app, logs.Les problèmes courants et où regarder : compilation, fenêtre, accès web, certificats, voix, application téléphone, journaux.

1. It does not buildÇa ne compile pas

  • find_package(utils) fails: libutils 4.0.0 or newer is missing or too old; install it (see Install).
  • FTXUI fails to download: the first configure fetches it (needs network); later builds reuse it.
  • Too many compilers at once freeze the computer: use nice -n 19 and --parallel 2 at most.
  • find_package(utils) échoue : libutils 4.0.0 ou plus est absent ou trop ancien ; installez-le (voir Installation).
  • FTXUI ne se télécharge pas : la première configuration le récupère (réseau nécessaire) ; les suivantes le réutilisent.
  • Trop de compilateurs à la fois figent l'ordinateur : utilisez nice -n 19 et --parallel 2 au plus.

2. --gui says there is no window--gui dit qu'il n'y a pas de fenêtre

The binary was built without Qt6 Widgets (or -DCLUSTER_GUI=OFF), or there is no display. Install the Qt6 development package and build again; the terminal interface always works.

Le binaire a été compilé sans Qt6 Widgets (ou avec -DCLUSTER_GUI=OFF), ou il n'y a pas d'affichage. Installez le paquet de développement Qt6 et recompilez ; l'interface terminal marche toujours.

3. The agent is not foundL'agent est introuvable

claude-cluster launches claude (or qwen, opencode, codex) by the names in [commands]. Check claude --version and claude-cluster auth list: it says which providers are ready and why not. A provider with a key needs claude-cluster auth login <provider>.

claude-cluster lance claude (ou qwen, opencode, codex) par les noms de [commands]. Vérifiez claude --version et claude-cluster auth list : il dit quels fournisseurs sont prêts et pourquoi pas. Un fournisseur à clé demande claude-cluster auth login <fournisseur>.

4. The web page does not loadLa page web ne se charge pas

  • Is the access open? The bottom right of the interface shows ● web https://<address>:8787 · code ...; claude-cluster web tells the state and why the outside is not reached.
  • The firewall may block the port ([web] port, 8787): firewall-cmd --add-port=8787/tcp.
  • The app does not find the computer (Search this network empty): the web access must be open, [web] discovery on, the phone on the same Wi-Fi, and UDP 8789 let in (firewall-cmd --add-port=8789/udp); a guest Wi-Fi often blocks broadcasts: type the address.
  • The browser must have a private address of a subnet of the computer; a public name pointed at the LAN is refused by design.
  • Your connection is not private: the certificate belongs to the authority of this computer. Trust it once per device from the login page (trust this computer once), or on this computer with claude-cluster web trust-ca.
  • The code is rejected: 5 wrong codes block the address for 15 minutes and rotate the code; the new code is on the computer.
  • Nothing happens after the code: the device waits for your approval on the computer (a popup and a notification with Allow).
  • L'accès est-il ouvert ? En bas à droite de l'interface : ● web https://<adresse>:8787 · code ... ; claude-cluster web donne l'état et pourquoi l'extérieur n'est pas joint.
  • Le pare-feu peut bloquer le port ([web] port, 8787) : firewall-cmd --add-port=8787/tcp.
  • L'app ne trouve pas l'ordinateur (Search this network vide) : l'accès web doit être ouvert, [web] discovery activé, le téléphone sur le même Wi-Fi, et l'UDP 8789 autorisé (firewall-cmd --add-port=8789/udp) ; un Wi-Fi invité bloque souvent les diffusions : tapez l'adresse.
  • Le navigateur doit avoir une adresse privée d'un sous-réseau de l'ordinateur ; un nom public pointé vers le réseau local est refusé par conception.
  • Votre connexion n'est pas privée : le certificat appartient à l'autorité de cet ordinateur. Approuvez-la une fois par appareil depuis la page de connexion (trust this computer once), ou sur cet ordinateur avec claude-cluster web trust-ca.
  • Le code est refusé : 5 codes faux bloquent l'adresse 15 minutes et changent le code ; le nouveau code est sur l'ordinateur.
  • Rien ne se passe après le code : l'appareil attend votre accord sur l'ordinateur (une fenêtre et une notification avec Allow).

5. The voice does not workLa voix ne marche pas

Run the palette action Voice: what is missing. The microphone needs https in a browser. claude-cluster engines tells which engines are ready. See Voice.

Lancez l'action de palette Voice: what is missing. Le micro demande https dans un navigateur. claude-cluster engines dit quels moteurs sont prêts. Voir Voix.

6. The phone appL'application téléphone

An app older than the one the computer serves is blocked by a popup until updated (Install: it downloads /app.apk from the computer). No notification? Allow notifications (Android 13+) and Keep running in the background in This device; some vendors kill background services: allow the app to autostart. A computer that is off or out of the network cannot be reached; there is no Google push. See Notifications and the phone app.

Une application plus ancienne que celle que sert l'ordinateur est bloquée par une fenêtre jusqu'à sa mise à jour (Install : elle télécharge /app.apk depuis l'ordinateur). Pas de notification ? Autorisez les notifications (Android 13+) et Keep running in the background dans This device ; certains constructeurs tuent les services d'arrière-plan : autorisez le démarrage automatique de l'application. Un ordinateur éteint ou hors réseau est inatteignable ; il n'y a pas de push Google. Voir Notifications et application téléphone.

7. ReconnectingReconnexion

A popup Reconnecting means the core was lost (killed, crashed, restarting): it retries 1, 2, 4... 10 s apart, starts the core again when it is gone and resumes the sessions. Retry now (r / Enter) or Quit (q). If another version runs the core (installed again while it ran) a new interface asks whether to replace it. A crashed core is normally started again by its watcher ([ui] restart_core, on) before you see anything; turned off, an interface starts it when it notices.

Une fenêtre Reconnecting signifie que le cœur est perdu (tué, planté, en redémarrage) : elle réessaie à 1, 2, 4... 10 s d'écart, relance le cœur s'il a disparu et reprend les sessions. Retry now (r / Entrée) ou Quit (q). Si une autre version fait tourner le cœur (réinstallée pendant qu'il tournait), une nouvelle interface demande s'il faut le remplacer. Un cœur planté est normalement relancé par son surveillant ([ui] restart_core, activé) avant que vous ne voyiez quoi que ce soit ; désactivé, une interface le relance quand elle s'en aperçoit.

8. Where the logs areOù sont les journaux

WhatWhere
core log~/.local/share/claude-cluster/core.log
conversations~/.local/share/claude-cluster/logs/<id>.jsonl
serviceclaude-cluster service logs (the journal of the user unit)
debug trace[debug] enabled = true, then debug.log in the data folder
what faileda popup what you did, where it failed, the error with OK / Retry

A bug report can include the debug trace, the version and commit shown at the bottom of this site.

QuoiOù
journal du cœur~/.local/share/claude-cluster/core.log
conversations~/.local/share/claude-cluster/logs/<id>.jsonl
serviceclaude-cluster service logs (le journal de l'unité utilisateur)
trace de debug[debug] enabled = true, puis debug.log dans le dossier de données
ce qui a échouéune fenêtre ce que vous avez fait, où ça a échoué, l'erreur avec OK / Retry

Un rapport de bug peut inclure la trace de debug, la version et le commit affichés en bas de ce site.