Dépanner un mod
Découvrez pourquoi un mod Claude Code ne fait rien : associez le symptôme ou le message à sa cause, consultez les messages de refus et lisez le journal de débogage.
Quand le module d'un mod ou l'un de ses hooks échoue, Claude Code l'ignore et la session continue, donc un mod cassé peut ressembler à un mod qui ne fait rien. Commencez par vérifier ce que Claude Code a lu à partir de votre mod et où il signale un problème, puis trouvez le symptôme ou le message que vous avez.
Découvrez pourquoi un mod ne fait rien
Quand un mod ne fait rien, deux vérifications trouvent la raison : ce que Claude Code lit à partir des fichiers du mod et la ligne qu'il écrit quand il ignore quelque chose. Pour la première, dans votre shell, exécutez claude plugin validate avec le répertoire du mod, comme dans claude plugin validate ./first-mod. Cela détecte un événement mal orthographié, un mauvais manifeste et un module que Claude Code ne peut pas lire, sans démarrer une session.
Quand un module ne se charge pas, un hook est ignoré ou un autre mod refuse le vôtre, Claude Code écrit une ligne qui nomme votre mod. L'endroit où vous lisez cette ligne dépend de la session :
- Une session qui recharge à chaud un répertoire de plugin : une ligne atténuée dans la transcription. C'est une session interactive que vous avez démarrée avec
--plugin-dir, ou une session où vous avez activé le rechargement à chaud pour les mods que Claude a écrits. - Toute autre session interactive, comme une qui exécute un mod que vous avez installé à partir d'une marketplace : le journal de débogage uniquement. Pour en obtenir un, démarrez la session avec
claude --debug. - Une exécution
claude -pavec--plugin-dir: stderr, au format de sortie texte par défaut. Un refus par un autre mod va au journal de débogage uniquement.
Vérifiez si les mods peuvent se charger
Pour vérifier si votre configuration permet aux mods de se charger du tout, sans en installer un, exécutez claude plugin test dans votre shell, à partir d'un répertoire qui ne contient pas de mod. Vous n'avez pas besoin d'une session. Le message qu'il affiche vous indique l'état :
| Le message inclut | Ce que cela signifie |
|---|---|
no hooks module to load |
Les mods peuvent se charger. La commande n'a trouvé aucun mod à tester dans ce répertoire. |
hooks modules are turned off here |
Un paramètre empêche vos mods : disableAllHooks dans vos propres paramètres, ou la politique de votre organisation |
hooks modules are turned off in this process |
Anthropic a désactivé les mods installés à distance. Aucun paramètre sur votre machine ne les réactive. |
Une organisation peut également définir allowManagedModsOnly pour autoriser uniquement ses propres mods, ce que cette commande ne signale pas. Dans ce cas, un mod que vous installez ne se charge pas, et un message explique pourquoi.
Le mod ne se charge pas
Rien de ce que le mod ajoute n'apparaît : aucune commande, aucun dessin et aucun changement de comportement.
Votre version est antérieure à 2.1.287
claude --version affiche une version antérieure à 2.1.287. Votre version est antérieure à l'activation des mods par défaut.
La ligne `mods active` ne nomme pas le mod
Rien de ce que le mod ajoute n'apparaît, et la ligne mods active dans /plugin ne le nomme pas. Le module hooks ne s'est pas chargé. Quand Claude Code l'a refusé, le journal de débogage a une ligne qui commence par hooks module, le nom du mod et not loaded:, comme dans hooks module first-mod@inline not loaded: disableAllHooks in managed settings pour un mod chargé avec --plugin-dir.
Lisez la raison après les deux points. La section messages de refus énumère chacun d'eux. Si le journal n'a pas de telle ligne, parcourez les autres entrées de ce groupe.
Une exécution `claude -p` affiche `hooks module not loaded`
La ligne commence par le nom du mod et va à stderr. Le module hooks a été refusé. Une exécution non-interactive n'a pas de transcription, donc le message va à stderr.
Lisez la raison après les deux points. La section messages de refus énumère chacun d'eux.
Messages de refus
Chacun de ceux-ci suit hooks module, le nom du mod et not loaded: dans le journal de débogage.
| Le message commence par | Ce que cela signifie |
|---|---|
hooks modules are turned off for installed plugins in this process |
Anthropic a désactivé les mods installés à distance. Aucun paramètre sur votre machine ne les réactive. |
disableAllHooks in managed settings |
Votre organisation a désactivé les hooks des plugins installés |
only managed plugins and built-in plugins run |
allowManagedHooksOnly est défini, ou disableAllHooks est défini dans un fichier de paramètres autre que les paramètres gérés |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Vous avez démarré Claude Code avec --bare |
another plugin of that name loads first |
Deux plugins partagent un nom. Le plugin géré, ou celui chargé en premier, est utilisé. |
Messages du garde intégré
Sur une machine avec des paramètres gérés, ou pour un utilisateur connecté avec un plan Team ou Enterprise, le garde intégré peut refuser un mod ou l'une de ses réponses. Chaque message nomme l'option que l'administrateur de votre organisation définit pour modifier la règle.
| Le message contient | Ce que cela signifie | Où cela apparaît |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
Votre organisation n'autorise que ses propres mods, donc le vôtre n'a pas été chargé | Le journal de débogage et la transcription dans une session qui recharge à chaud un répertoire de plugin |
tried to lift a deny rule in your settings |
Le hook tool.check de votre mod a approuvé un appel qu'une règle deny refuse. L'appel reste refusé. |
La transcription et le journal de débogage, une fois pour chaque mod dans une session. Dans une exécution claude -p, le journal de débogage uniquement. |
the deny rules in your settings could not be checked for this call, so it is refused |
Le garde a échoué lors de la vérification d'un appel qu'un mod a approuvé, donc il a refusé l'appel | La raison que Claude lit pour l'appel refusé |
`validate` réussit et ne liste aucune ligne `hooks`
hooks/hooks.json n'a pas de clé modules, ou la clé est mal orthographiée.
Ajoutez "modules": ["./register.js"].
`hooks module did not load`
La ligne commence par le nom du mod, puis hooks module did not load: et une raison, qui donne le fichier et la ligne quand le problème est dans votre code. Claude Code n'a pas pu charger le module, par exemple parce que son code de niveau supérieur a levé une exception.
Corrigez l'erreur que la raison nomme.
`options do not fit plugin.json userConfig`
La ligne commence par le nom du mod, puis hooks module did not load: options do not fit plugin.json userConfig: et une raison. Une option ne correspond pas à son champ userConfig, comme un nombre au-dessus du max du champ, ou un champ obligatoire n'a pas de valeur.
Définissez ou modifiez la valeur. La fin de la ligne nomme son entrée pluginConfigs dans settings.json.
Aucun mod ne se charge dans un répertoire que vous avez ouvert pour la première fois
Vous n'avez pas répondu à l'invite de confiance pour le répertoire.
Démarrez une session interactive dans ce répertoire avec claude et acceptez l'invite de confiance qu'elle ouvre.
Aucun plugin installé ne se charge du tout
Vous avez démarré Claude Code avec --safe-mode.
Démarrez sans le drapeau.
Un hook est ignoré ou un mod est déchargé
Le mod s'est chargé, puis Claude Code a ignoré l'un de ses hooks ou l'a déchargé.
`hook skipped`
La ligne nomme le mod et l'événement, puis dit hook skipped: et une raison, comme dans first-mod: tool.call hook skipped: threw Error: boom. Un hook a levé une exception, a dépassé sa limite de temps de 10 secondes, ou a retourné un résultat de la mauvaise forme. La ligne apparaît une fois pour chaque événement et type d'échec jusqu'à ce que le mod se recharge.
Corrigez l'erreur. Le journal de débogage a une ligne pour chaque occurrence.
`it crashed the hooks worker`
La ligne commence par le nom du mod, comme dans first-mod was unloaded: it crashed the hooks worker. Les mods installés partagent un thread de travail. Le worker a cessé de répondre ou s'est écrasé, et Claude Code a tracé cela jusqu'à ce mod et l'a déchargé. Un hook qui bloque le thread, comme une boucle qui n'attend jamais, en est une cause.
Corrigez le hook.
`mods that run in the hooks worker are off for this session`
La ligne lit hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Le worker s'est arrêté trois fois et Claude Code n'a pas pu tracer les arrêts jusqu'à un mod, donc il a déchargé tous les mods qui ne sont pas intégrés, y compris les mods que votre organisation installe. Cette ligne atteint la transcription dans chaque session interactive.
Exécutez /reload-plugins pour les charger à nouveau.
Un appel d'outil est refusé
Le mod s'est chargé et ses hooks s'exécutent, et un appel d'outil qu'il a touché est refusé.
`a hook changed this call's input after the model wrote it`
En mode auto, un appel d'outil refusé donne cette raison. Un hook a modifié l'entrée de l'appel d'outil après que le classificateur côté serveur l'ait examiné, donc cet examen ne couvre pas ce qui s'exécuterait. Le hook peut être un hook tool.call ou turn.step d'un mod, ou un hook de paramètres PreToolUse. Le message ne dit pas lequel.
Le message indique à Claude d'émettre l'appel une fois de plus tel qu'enregistré. Si cela est également refusé, le hook modifie l'entrée à chaque fois, donc désactivez le mod ou le hook, ou quittez le mode auto et approuvez l'appel vous-même.
Un message sur les règles de refus dans vos paramètres
tried to lift a deny rule in your settings et the deny rules in your settings could not be checked for this call, so it is refused proviennent tous deux du garde intégré.
Consultez-les dans Messages du garde intégré.
Un dessin n'apparaît pas ou ne répond pas
Le mod s'est chargé, et son volet, sa bande ou ses contrôles ne se comportent pas comme prévu.
Un volet ou une bande est vide ou affiche le contenu habituel de Claude Code
L'arbre que votre hook a retourné n'a pas validé. Avec --plugin-dir, la transcription dit ui.render (Pane) refused: avec la raison, comme dans first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Le journal de débogage a a hook returned a tree that does not validate avec la même raison.
Lisez la raison sur cette ligne. Les causes courantes sont une prop que l'élément ne prend pas et un élément que l'application n'a pas.
`$.ui.open` s'exécute et aucun volet n'apparaît
L'appel ne venait pas de quelque chose que l'utilisateur a fait, et le terminal est plus étroit que 144 colonnes.
Ouvrez le volet à partir d'une commande ou d'un bouton, ou vérifiez le résultat isPlaced de l'appel. Voir Ouvrir un volet au bon moment.
Les raccourcis clavier ne font rien
Votre volet n'a pas le focus clavier.
Appuyez sur Ctrl+X puis Tab, ou cliquez sur le volet. Ouvrez-le avec focus: true à partir d'une commande.
Un dessin fonctionne dans le terminal et pas dans l'application de bureau
Le site ou l'élément n'est pas disponible là.
Vérifiez les sites de rendu et les tableaux éléments.
Une modification ou une valeur est perdue
Le mod s'exécute, et une modification que vous avez apportée ou une valeur qu'il a conservée n'est pas là.
Vos modifications ne prennent pas effet
Vous modifiez un plugin que vous avez installé. Claude Code exécute la copie en cache pour la version installée.
Développez avec --plugin-dir pointant vers votre copie de travail, comme dans claude --plugin-dir ./first-mod, qui se recharge quand vous enregistrez.
Une valeur se réinitialise quand le module se recharge
Les variables au niveau du module sont réinitialisées à chaque rechargement.
Conservez la valeur dans $.state ou $.store.
Une valeur se réinitialise après `/clear`, `/resume` ou `/branch`
Une valeur se réinitialise, ou une valeur enregistrée est remplacée par sa valeur par défaut. Chacune de ces commandes réinitialise $.state à ses valeurs par défaut, et session.start ne se déclenche pas à nouveau.
Rechargez la valeur enregistrée à nouveau dans un hook classic.SessionStart.
Lisez le journal de débogage
Le journal de débogage a une ligne pour chaque module que Claude Code charge ou refuse, chaque hook qui échoue et chaque résultat qu'il refuse, donc c'est là qu'il faut regarder quand la transcription ne montre rien. Pour en écrire un, dans votre shell, démarrez Claude Code avec --debug, ou avec --debug-file <path> pour choisir où il va :
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
Dans un autre terminal, suivez le fichier et filtrez par le nom de votre mod :
tail -f ./mod-debug.log | grep first-mod
Un mod qui s'est chargé a une ligne qui le nomme et énumère les événements qu'il accroche. Un mod chargé avec --plugin-dir apparaît sous son nom suivi de @inline :
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
Un dessin qui n'a pas validé compte comme un résultat refusé et obtient aussi une ligne. Pour écrire vos propres lignes dans le journal, appelez $.ui.log avec un deuxième argument, comme dans $.ui.log('message', { to: 'debug' }). Sans le deuxième argument, $.ui.log ajoute une ligne atténuée à la transcription.
Pendant que vous modifiez un mod chargé avec --plugin-dir, la transcription affiche une ligne pour chaque rechargement qui nomme le mod et énumère ses hooks. Si une sauvegarde casse le module, la ligne dit reload failed, the previous version stays loaded: avec la raison, et la dernière version de travail continue de s'exécuter.
Étapes suivantes
- Testez un mod : détectez les problèmes avant qu'ils n'atteignent une session
- Dépannez les plugins : problèmes d'installation et de chargement d'un plugin qui ne sont pas spécifiques aux mods