Chapitre 7 · Chapitre 7 · Sécurité, limites et projet final
7.4 Erreurs fréquentes et dépannage
Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.
Suivre gratuitementVoici le tableau de dépannage de la formation, présenté symptôme par symptôme. Pour chaque cas : la cause probable, puis la solution.
Le hook n'apparaît pas dans /hooks
Cause : JSON invalide ou mauvais fichier. Solution : retire la virgule finale ou le commentaire, vérifie l'emplacement (.claude/settings.json ou ~/.claude/settings.json). Si rien n'apparaît après quelques secondes, redémarre la session.
Il apparaît mais ne se déclenche jamais
Cause : matcher mal écrit (casse) ou mauvais événement. Solution : Edit|Write, pas edit|write ; pour empêcher, c'est PreToolUse. Vérifie aussi que tu as accepté la confiance du dossier, et qu'aucun if n'est posé sur un événement non lié aux outils.
« command not found »
Cause : chemin relatif. Solution : utilise $CLAUDE_PROJECT_DIR, entre guillemets.
« jq: command not found »
Cause : jq absent. Solution : installe jq ou écris le hook en Node ou Python.
Message sur Git Bash (Windows)
Cause : Git Bash introuvable. Solution : installe Git pour Windows ou ajoute "shell": "powershell", avec $env:CLAUDE_PROJECT_DIR dans la commande.
« Unexpected token » au test manuel sous PowerShell 5.1
Cause : BOM ajouté par le pipe. Solution : teste avec node script.mjs < evenement.json dans cmd.
Le JSON renvoyé n'a aucun effet
Cause : champ au mauvais niveau ou texte avant le {. Solution : mets les champs dans hookSpecificOutput, et envoie tes traces de débogage sur stderr.
Claude ne voit pas mon message
Cause : message sur stdout avec exit 2, ou exit 0 avec stderr. Solution : exit 2 + console.error.
Mon blocage ne bloque pas
Cause : le script sort avec 1, ou plante avant process.exit(2). Solution : pour imposer une règle, utilise toujours exit 2, et teste le cas d'erreur à la main.
Claude n'arrête plus de travailler
Cause : hook Stop qui bloque en boucle. Solution : lis stop_hook_active et sors avec 0.
« Only hooks from managed settings run here »
Cause : ton organisation n'autorise que ses propres hooks. Solution : vois avec ton administrateur.
Le prompt de dépannage
Mon hook
configuré dans .claude/settings.json ne fonctionne pas. Voici le fichier de réglages et le script. Vérifie le JSON, le matcher, l'événement choisi et la gestion des codes de sortie, puis propose-moi une commande pour le tester avec un faux événement. N'active rien sans mon accord.
Les trois outils d'observation
/hooks → le hook est-il chargé, sous le bon événement ?
Ctrl+O → que s'est-il passé (succès, blocage, hook error) ?
claude --debug ou /debug → journal détaillé dans ~/.claude/debug/
Dans le journal, deux messages de la doc sont particulièrement utiles : « Hook output does not start with { » (du texte parasite avant ton JSON) et « Hook JSON output had unrecognized keys » (un champ au mauvais niveau).
Si ça coince
- Aucune piste ne correspond. Coupe tous les hooks avec
"disableAllHooks": true: si le problème disparaît, réactive-les un par un. - Le problème n'apparaît qu'en session, jamais à la main. Compare le JSON réel (leçon 4.1, script espion) avec ton événement de test.
- Tu as tout vérifié. Relis la section de dépannage de la page « Automate actions with hooks » de la doc : elle évolue avec les versions.
À retenir
- Commence toujours par
/hooks, puis Ctrl+O, puis le journal de débogage. - La plupart des pannes viennent du JSON, de la casse du matcher ou du chemin du script.
- Message de blocage : sur stderr, avec exit 2.
disableAllHookspermet d'isoler un hook fautif.