Skip to content
Floskool

Chapter 7 · Chapitre 7 · Sécurité, limites et projet final

7.4 Erreurs fréquentes et dépannage

Free lesson 6 minGroup Claude Code & IA

Follow this course in your space: your progress is saved, and the community answers your questions.

Follow for free

Voici 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.
  • disableAllHooks permet d'isoler un hook fautif.