Troubleshooting.fr

Dépannage

Les problèmes les plus fréquents et comment les résoudre rapidement.

---

🚨 Outils de diagnostic avant tout

1. Paramètres → Diagnostic — vérifie automatiquement : Node, Python, Git, Claude CLI, connexions IA, MCP
2. Logs — logs/workflow.log est votre meilleur ami
3. Kanban → carte → Logs — logs filtrés pour une tâche précise
4. Console DevTools : View → Toggle Developer Tools (ou Ctrl+Shift+I)

---

🔧 Installation

Node.js introuvable

Symptôme : erreur « node: command not found » au lancement.

Solution :

• Réinstallez depuis nodejs.org en cochant « Add to PATH »
• Windows : fermez et rouvrez le terminal après installation
• Vérifiez : node --version doit retourner v20+

Modules natifs qui échouent (xterm, node-pty…)

Symptôme : erreur NODE_MODULE_VERSION mismatch ou binary incompatible.

Solution :

cd apps/frontend
pnpm run rebuild

Python manquant ou mauvaise version

Symptôme : erreur python: command not found ou Python 2.7.

Solution :

• Installez Python 3.12+
• Windows : winget install Python.Python.3.12
• macOS : brew install python@3.12
• Linux : sudo apt install python3.12 python3.12-venv
• Vérifiez avec python --version (utilisez python3 sur macOS/Linux si besoin)

uv introuvable

Symptôme : scripts d'install échouent.

Solution :

# Installer uv
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux
# ou
pipx install uv                                   # toutes plateformes

---

🔑 Authentification

Token Claude expiré

Symptôme : « 401 Unauthorized » ou « invalid token ».

Solution :

claude
# Tapez /login dans le prompt

Ou depuis l'application : Paramètres → Fournisseurs IA → Claude → Re-authenticate.

API Key invalide

Symptôme : 401/403 lors des appels.

Solution :

• Vérifiez .env-files/.env (pas d'espaces, pas de guillemets autour de la valeur)
• Vérifiez les scopes côté fournisseur
• Regénérez la clé côté fournisseur et mettez à jour

Problème OAuth

Symptôme : le popup OAuth se ferme immédiatement ou revient sur une page blanche.

Solution :

1. Dans le provider (Anthropic, OpenAI…), révoquer l'app WorkPilot AI
2. Dans WorkPilot AI, supprimer le profil
3. Recréer le profil et re-authentifier

Plusieurs comptes confondus

Symptôme : les tokens semblent se « mélanger » entre profils.

Solution : vérifiez dans le trousseau OS (Keychain / Credential Manager) que chaque profil a bien son entrée distincte.

---

⚙️ Exécution des agents

L'agent reste bloqué

Symptôme : barre de progression figée depuis plusieurs minutes.

Solutions :

1. Ouvrez le terminal de l'agent — lit-il encore le LLM ?
2. Regardez logs/workflow.log en live : tail -f logs/workflow.log
3. Si vraiment bloqué : bouton Abort puis relancez
4. Problème récurrent ? Augmentez le timeout dans Paramètres → Sécurité → Timeouts

Rate limit atteint

Symptôme : « Rate limit exceeded » dans les logs.

Solutions :

• Si plusieurs profils configurés, WorkPilot AI bascule automatiquement — vérifiez le statut dans Analytics → Rate Limits
• Sinon, ajoutez un profil secondaire (même fournisseur ou autre)
• Réduisez le parallélisme : Paramètres → Agents → Limite

Le QA loop ne converge pas

Symptôme : la tâche atteint 50 itérations sans succès.

Causes courantes :

• Critères d'acceptation flous — réécrivez-les mesurables
• Test instable — tests flaky qui passent une fois sur deux
• Conflit entre critères — un critère impose X, un autre interdit X
• Contexte manquant — l'agent ignore un fichier important

Solutions :

1. Inspectez le dernier qa_report.md
2. Utilisez Agent Replay pour voir où ça diverge
3. Ajoutez un fichier à context.json
4. Reformulez les critères

Le Coder recrée des fichiers au lieu de modifier

Symptôme : nouveaux fichiers au lieu d'éditions.

Solution :

• Enrichissez context.json avec les fichiers existants concernés
• Précisez dans la spec : « modifier src/auth.ts existant »
• Vérifiez que la permission de lecture/écriture est bien accordée

---

🌳 Git / Worktrees

Worktree corrompu

Symptôme : impossible de fusionner, git signale des incohérences.

Solution :

# Lister les worktrees
git worktree list

# Supprimer un worktree
git worktree remove .worktrees/workpilot-ai/<nom> --force

# Nettoyer les références orphelines
git worktree prune

Conflit de fusion sémantique

Symptôme : la fusion automatique échoue et demande une résolution manuelle.

Solution :

• Ouvrez le worktree : cd .worktrees/workpilot-ai/
• Mergez manuellement vers develop
• Résolvez les conflits (VS Code, éditeur au choix)
• Retour à WorkPilot AI → Mark as merged

Branche protégée

Symptôme : « push to protected branch rejected ».

Solution :

• WorkPilot AI cible develop par défaut
• Si vous avez configuré main, changez dans Paramètres → Projet → Branche par défaut
• Créez une PR plutôt qu'un push direct

---

🌐 Intégrations

GitHub rate limit

Symptôme : erreurs 403 sur les appels GitHub API.

Solutions :

• Utilisez un Personal Access Token (quota plus large)
• Activez GitHub Actions self-hosted runners si CI intensive
• Espacez les batch operations

grepai ne répond pas

Symptôme : recherche sémantique qui retombe sur grep classique.

Solution :

curl http://localhost:9000/health
# Si non démarré :
cd src/connectors/grepai
python grepai_launcher.py

Graphiti ne retourne rien

Symptôme : requêtes mémoire vides.

Solutions :

# Vérifier la connexion
python -c "from integrations.graphiti.client import check_connection; print(check_connection())"

# Vérifier la variable
echo $GRAPHITI_ENABLED   # doit être true

# Vérifier qu'il y a bien eu ingestion (specs terminées)
# Les nouvelles installations ont un graphe vide au départ

Chrome DevTools MCP ne se connecte pas

Symptôme : outils navigateur non disponibles.

Solutions :

• Vérifiez CHROME_DEVTOOLS_MCP_ENABLED=true
• Si CHROME_DEVTOOLS_PORT est défini, Chrome doit tourner sur ce port en debug (chrome --remote-debugging-port=9222)
• Sinon, l'agent lance un Chrome headless — vérifiez que Chromium est disponible

Windsurf — réponses 0 octet

Symptôme : appels Windsurf qui renvoient silencieusement du vide.

Cause : utilisation de application/grpc au lieu de Connect protocol.

Solution : utiliser application/connect+proto pour streaming, application/proto pour unary. CSRF token depuis state.vscdb est souvent périmé — lire plutôt via psutil dans l'environnement du process Windsurf.

---

🖥 Interface

UI très lente

Symptômes : scrolling saccadé, terminaux qui rament.

Solutions :

• Fermez les terminaux inutiles (max 12, mais moins c'est mieux)
• Désactivez les animations : Paramètres → Apparence → Animations
• Redémarrez l'application
• Vérifiez la RAM : WorkPilot AI aime 16 Go

Thème ne s'applique pas

Symptôme : flash de blanc au démarrage.

Solution :

• Si thème custom : export puis import pour forcer la réapplication
• Vérifiez settings.json dans le dossier app (%APPDATA% / ~/Library/Application Support/ / ~/.config/)

Terminaux Claude qui se ferment tout seul

Symptôme : le terminal affiche Claude: exit status 1 puis se ferme.

Solution :

• Lancez claude --version — mettez à jour si ancien
• Vérifiez CLAUDE_CODE_OAUTH_TOKEN encore valide
• Regardez les logs : logs/terminal.log

---

💾 Stockage et données

Espace disque saturé

Cause typique : accumulation de worktrees et de logs.

Solution :

# Lister les worktrees inutiles
git worktree list

# Supprimer ceux qui sont mergés
git worktree remove .worktrees/workpilot-ai/<nom>

# Nettoyer les logs
# Paramètres → Avancé → Clean logs older than X days

Spec corrompue

Symptôme : erreur au chargement d'une spec.

Solution :

• Fichier .workpilot/specs/<nom>/ — vérifiez la structure
• JSON mal formé ? Restaurez depuis git si versionné, sinon supprimez la spec et recréez
• Utiliser : python validate_spec.py --spec-dir .workpilot/specs/<nom> --checkpoint all

---

📊 Performance

Consommation de tokens excessive

Solutions :

• Vérifiez context.json — trop de fichiers chargés ?
• Baissez le budget thinking sur les phases non critiques
• Utilisez un modèle moins cher (Haiku) pour les phases simples
• Compactez le graphe Graphiti : python -m integrations.graphiti.maintenance --compact
• Activez le skill token_optimizer (déjà par défaut)

Tâches de type SIMPLE jugées COMPLEX

Cause : l'évaluateur de complexité sur-estime.

Solution :

• Forcez avec --complexity simple en CLI
• Côté UI : Nouvelle tâche → Options avancées → Complexité

---

🐛 Crashes

Electron crash au démarrage

Solutions :

• Supprimez le cache : %APPDATA%/WorkPilot-AI/Cache (Windows) / ~/Library/Caches/WorkPilot-AI/ (macOS)
• Démarrez en safe mode : pnpm run dev:safe
• Regardez les logs du main process

Backend Python crash

Solutions :

cd apps/backend
source .venv/bin/activate
python -c "import main"   # identifier une erreur d'import
pip install -r requirements.txt   # réinstaller les deps

---

🆘 Si rien ne marche

1. Mettez à jour WorkPilot AI (nouvelle release peut corriger votre bug)
2. Redémarrez complètement (app + OS au besoin)
3. Collectez les logs : logs/workflow.log, logs/security.log, console DevTools
4. Ouvrez une issue avec :
   • Version (Paramètres → À propos)
   • OS et version
   • Étapes de reproduction
   • Logs pertinents
   • Captures d'écran si possible
5. Rejoignez le Discord : discord.gg/KCXaPBr4Dj

---

Prochaine étape

➡️ FAQ