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, vérifiez 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 vérification, 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ù le rechargement à chaud est activé 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 -p avec --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 :

Une organisation peut également définir allowManagedModsOnly pour autoriser uniquement ses propres mods, ce que cette commande ne signale pas. Dans ce cas, Claude Code refuse un mod que vous installez, 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 trop ancienne

Consultez quelle version utiliser et comment vérifier la vôtre.

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.

Certains paramètres arrêtent un mod et laissent le reste de son plugin fonctionner. Activer ou désactiver les mods les nomme.

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.

Messages du garde intégré

Là où le garde-fou intégré se charge, il 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.

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.

Si la raison se termine par ; the version loaded before is unloaded, aucune version du mod ne s'exécute actuellement. Une fois l'erreur corrigée, exécutez /reload-plugins dans la session pour charger à nouveau le mod. Si vous avez installé le mod sans l'avoir écrit, demandez à son auteur de corriger l'erreur.

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 échoue à la validation par rapport à 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.

code nested too deep to scan: more than 2000 scopes

La ligne commence par le nom du mod, puis hooks module did not load:, le fichier et code nested too deep to scan: more than 2000 scopes. Un fichier d'un module de hooks ne peut pas imbriquer des portées, comme des fonctions, des blocs et des boucles, sur plus de 2 000 niveaux. claude plugin validate signale la même raison.

Réécrivez le code pour que ses portées soient moins profondément imbriquées.

the engine ran out of stack linking the file and its imports

Le code du module de hooks est trop profondément imbriqué, ou sa chaîne d'imports est trop longue, pour que Claude Code puisse le charger. La ligne commence par le nom du mod et hooks module did not load:, puis donne le nom d'un fichier et cette raison.

Parcourez ce fichier et les fichiers atteints via ses imports pour trouver la partie la plus profondément imbriquée, et réécrivez-la pour réduire l'imbrication, ou raccourcissez la chaîne d'imports. Si vous n'avez pas écrit le mod, demandez à son auteur de le corriger.

the parser stopped ou the engine ran out of stack loading the file

Le code d'un fichier du module de hooks est imbriqué si profondément que Claude Code a manqué de pile en le lisant. La ligne commence par le nom du mod et hooks module did not load:, puis donne le nom de ce fichier et l'une de ces raisons :

• code nested too deep to scan (the parser stopped: <message>)
• the engine ran out of stack loading the file (code nested too deep): <message>

La raison ne donne aucun numéro de ligne et n'indique pas quel type de code est imbriqué : parcourez donc vous-même le fichier pour trouver sa partie la plus profondément imbriquée. Réécrivez cette partie pour réduire l'imbrication. Si vous avez installé le mod sans l'avoir écrit, demandez à son auteur de le faire.

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.

Claude Code cesse de demander l'activation du rechargement à chaud

Claude écrit un mod dans une session interactive, rien ne se charge, et Claude Code ne demande plus s'il faut activer le rechargement à chaud. Si la question se termine trois fois sans qu'aucune réponse soit choisie, le rechargement à chaud reste désactivé. Par exemple, la question se termine ainsi lorsque vous définissez askUserQuestionTimeout et que le délai expire avant votre réponse. Ce paramètre s'applique ici car Claude Code pose la question dans la même boîte de dialogue de question qu'utilise AskUserQuestion. Une question que vous fermez vous-même ne compte pas parmi les trois.

Pour exécuter le mod, copiez son répertoire hors du dossier des mods, puis, dans votre shell, démarrez une nouvelle session avec --plugin-dir, comme dans claude --plugin-dir ~/mods/git-branch.

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, 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.

no command.run hook answered it

Vous exécutez une commande que votre mod a ajoutée, et la réponse nomme le mod et la commande, comme dans first-mod registered /tally but no command.run hook answered it, puis vous dit d'ajouter un hook. Claude Code imprime cette réponse quand la commande atteint la fin de la chaîne sans réponse, ce qui se produit dans deux cas :

• Aucun hook n'a répondu à la commande : le module n'a pas de hook command.run, le filtre du hook nomme une commande différente, ou le hook a retourné next(e)
• Claude Code a ignoré le hook : hook skipped énumère les raisons. Passer focus: false à $.ui.open est une façon d'y arriver.

Si le module a déjà le hook que la réponse décrit, cherchez une ligne hook skipped qui nomme command.run, qui donne la raison. Un test qui exécute la commande échoue avec la même raison.

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.

its session.start ran again in a fresh copy

La ligne commence par le nom du mod et nomme un appel $.prompt.submit, $.command.run ou $.agent.spawn, comme dans first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again. Claude Code a rechargé le module du mod, par exemple après que le hooks worker s'est écrasé et a été remplacé, et le hook session.start de la nouvelle copie s'est exécuté. L'appel nommé par la ligne s'est résolu avec le résultat de sa première exécution au lieu de s'exécuter à nouveau, de sorte que votre mod ne soumet pas le prompt, n'exécute pas la commande et ne démarre pas le sous-agent deux fois. Le reste du hook s'est exécuté normalement.

Il n'y a rien à corriger.

Avant la v2.1.292, l'appel s'exécutait une seconde fois, de sorte que le prompt était soumis, la commande exécutée ou le sous-agent démarré deux fois.

This mod's change didn't load or the earlier version is no longer running

Une modification d'un mod que Claude a écrit dans cette session n'a pas pu se charger. La ligne de la transcription commence par le nom du mod et se termine par la raison :

• This mod's change didn't load, so the earlier version is still running: <reason>.
• This mod didn't load, and the earlier version is no longer running: <reason>.

Claude ne voit pas cette ligne ; collez-la donc dans votre prochain message lorsque vous demandez une correction à Claude.

$.agent.register refused: the hooks module that made the call is no longer loaded

La ligne commence par le nom de votre mod, comme dans first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed), et l'agent n'est pas enregistré. Votre mod a été rechargé ou déchargé avant l'appel. Un rechargement charge une nouvelle copie du module de hooks, et cet appel provenait de code qui s'exécutait encore dans l'ancienne copie, comme un hook qui n'avait pas encore retourné.

Si ce hook n'intercepte pas le rejet, il échoue et Claude Code l'ignore. Pour enregistrer l'agent depuis la copie qui reste chargée, effectuez l'appel dans votre hook session.start, qui s'exécute à nouveau dans chaque nouvelle copie après un rechargement.

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.

[!NOTE]

Dans certaines sessions de terminal interactives et sessions VS Code, le même refus donne la raison a hook changed this call's input after auto mode reviewed it. L'appel répété y porte la première modification du mod, et un hook tool.call s'exécute toujours dessus, mais toute modification supplémentaire est ignorée. Vous n'avez pas besoin de modifier votre mod, sauf si Claude vous indique dans sa réponse que le mode auto n'a pas pu vérifier l'appel.

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é.

Une notification s'affiche après l'arrêt d'un tour

Stopped: type a message to continue; a mod cannot resume work after Stop

Cette notification signifie qu'après l'arrêt du tour, par exemple avec Échap, un mod a tenté de lancer une tâche de lui-même et Claude Code l'en a empêché. Aucune correction n'est nécessaire. Après votre prochain message, les mods peuvent de nouveau lancer des tâches et une partie de ce travail reprend d'elle-même. Si ce que vous attendiez du mod ne revient pas, demandez-le à nouveau ou exécutez de nouveau la commande du mod.

Si vous avez écrit le mod, consultez Appels et travail en arrière-plan après l'interruption d'un tour par l'utilisateur.

Un dessin n'apparaît pas ou ne répond pas

Le mod s'est chargé, mais son volet, sa bande, son toast ou ses contrôles ne se comportent pas comme prévu.

La bande d'un autre mod s'affiche et pas la vôtre

Il n'y a qu'une seule bande au-dessus du prompt, et tous les mods la partagent. Un mod qui s'exécute avant le vôtre remplace votre bande lorsqu'il renvoie un arbre qui ne contient pas le résultat de next(e). Pour afficher les deux bandes, modifiez le hook de ce mod, ou demandez à son auteur de le faire :

• Conserver les bandes qui le suivent : placez le résultat de await next(e) parmi les enfants d'un Box dans son arbre, comme dans l'onglet Band above the prompt de Choisir où dessiner
• Garder l'arbre valide : ne donnez à ce Box, ni à aucun Box qui l'entoure, de prop width, height, minWidth, minHeight, position, top, left, right, bottom, display ou overflow

Pour trouver ce mod, écrivez un log de débogage et recherchez-y answered ui.render without next(). Une ligne telle que other-mod (user) answered ui.render without next() nomme un mod qui a renvoyé son arbre sans appeler next(e). Elle ne nomme pas le point de rendu, de sorte qu'un mod qui ne dessine qu'un volet peut aussi y apparaître. Un mod qui appelle next(e) puis ignore le résultat ne génère aucune ligne ; vérifiez donc aussi les hooks qui précèdent le vôtre.

La bande d'un mod est également absente lorsque l'arbre renvoyé par son propre hook n'est pas valide, et les bandes des autres mods restent affichées. Pour savoir de quel mod il s'agit et pourquoi, écrivez un log de débogage et recherchez-y ui.render hook skipped.

Un volet ou une bande est vide ou affiche le contenu habituel de Claude Code

L'arbre renvoyé par votre hook n'est pas valide. Une ligne hook skipped dans la transcription ou le log de débogage nomme votre mod et la raison, comme celle-ci pour un Box dans un volet :

first-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse)

Corrigez ce que la raison indique. Si la raison est tronquée, écrivez un log de débogage et recherchez-y a hook returned a tree that does not validate pour lire la suite.

Si la ligne indique plutôt refused: juste après le nom du point de rendu, comme dans ui.render (Pane) refused:, consultez Une ligne ui.render indique refused.

Une ligne ui.render indique refused

ui.render (<site>) refused:, ou ui.render (<site>): the chain settled on a tree that does not validate dans le log de débogage, signifie que l'arbre à ce point de rendu dépasse une limite de taille. Chacune de ces lignes nomme le point de rendu, puis la raison, et la raison nomme la limite.

Modifiez les mods qui dessinent à ce point de rendu pour que leurs hooks ui.render renvoient des arbres plus petits, ou demandez à leurs auteurs de le faire. Si la ligne de la transcription commence par hooks, plusieurs mods chargés ont un hook ui.render pour ce point de rendu ; vérifiez donc l'arbre de chacun de ces mods. Pour plusieurs mods dont les bandes au-dessus du prompt s'imbriquent en un arbre de plus de 32 niveaux de profondeur, la ligne indique :

hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn

Avant la v2.1.307, une ligne refused: pour n'importe quel point de rendu signalait tout arbre non valide, et pour Pane et AbovePrompt elle se terminait par ; the engine drew its own. Sur ces versions, corrigez ce que la raison indique.

needs a key, is drawn twice ou key each once

Un élément de l'arbre renvoyé par votre hook ui.render n'a pas de key valide, ou deux éléments partagent la même. Repérez le message que vous avez reçu :

• <Input> needs a key ou <Select> needs a key : l'élément n'a pas de prop key, ou sa key est vide ou n'est pas une chaîne, comme dans key: 3. Donnez-lui une chaîne non vide comme key.
• <Button> needs a key : donnez au bouton une chaîne non vide comme key
• is drawn twice; each takes its own key : deux éléments du type nommé par le message ont la même key, comme dans Input "size" is drawn twice; each takes its own key. Donnez à chaque élément sa propre key.
• key each once provenant de press dans un test : le dessin contient plusieurs boutons avec la clé que vous avez passée. Les boutons ayant le même libellé et sans prop key partagent ce libellé comme clé. Donnez à chaque bouton sa propre key.

Une ligne ui.render indique threw while drawn

La ligne nomme le point de rendu, puis indique threw while drawn: et l'erreur, comme dans first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own. Claude Code a rencontré cette erreur en dessinant l'arbre renvoyé par votre hook ui.render, ou en dessinant le point de rendu à partir des props que votre hook a passées à next. La terminaison the engine drew its own signifie que le point de rendu affiche le contenu habituel de Claude Code.

Lisez l'erreur et corrigez la valeur de votre hook qui l'a provoquée.

Avant la v2.1.289, cette erreur dans une ligne de la transcription mettait fin à la session avec Claude Code exited after an unrecoverable interface error.

the module failed without a message

Un Client a échoué avec une erreur sans message, comme throw new Error(). La ligne affichée à sa place ressemble à my-mod: Client client/spinner.js: the module failed without a message.

Trouvez le throw dans le code de votre Client et donnez un message à l'erreur. La ligne affiche alors ce message.

Avant la v2.1.289, la ligne affichait Error comme raison.

$.ui.open s'exécute et aucun volet n'apparaît

L'appel ne provient pas d'une action de l'utilisateur, et le terminal est plus étroit que la largeur dont ce volet a besoin.

Ouvrez le volet depuis une commande ou un bouton, ou vérifiez le résultat isPlaced de l'appel. Consultez Ouvrir un volet au bon moment.

Un toast n'apparaît pas

Votre mod appelle $.ui.toast dans une session de terminal interactive et vous ne voyez pas le toast. Pour confirmer que l'appel s'est exécuté, recherchez dans le log de débogage une ligne contenant le nom de votre mod et le texte du toast, comme $.ui.toast (first-mod): build finished. Vérifiez ensuite les causes suivantes :

• La ligne de l'appel est absente : recherchez une ligne indiquant pourquoi Claude Code a refusé l'appel, comme first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000.
• Un volet retient les toasts : votre mod ou un autre a passé holdToasts lors de l'ouverture du volet affiché. Fermez le volet pour mettre fin à la retenue. Si le volet est le vôtre et doit rester ouvert, retirez holdToasts de son appel $.ui.open et rouvrez le volet.
• Le toast se trouve sous le prompt : dans le moteur de rendu classique, regardez à droite sous le prompt. Un toast à cet endroit est une ligne qui commence par le nom du mod, plutôt qu'une boîte en haut à droite.
• Votre mod a affiché un toast plus récent : dans le moteur de rendu classique, un toast plus récent de votre mod peut remplacer celui qui est affiché ou en attente d'affichage. Le log de débogage contient une autre ligne pour l'ancien toast, qui se termine par gave way, cut short s'il était affiché, ou par gave way, unseen s'il n'est jamais apparu. Pour afficher les deux messages, regroupez-les dans un seul toast.
• Le toast a expiré sans être dessiné : en rendu plein écran, Claude Code dessine au plus trois toasts à la fois, de sorte qu'un toast peut expirer avant d'être dessiné. Le log de débogage contient une autre ligne pour ce toast, qui se termine par left the stack, never drawn. Lorsque votre mod en affiche plusieurs à la fois, regroupez les messages dans un seul toast.

Avant la v2.1.290, Claude Code ignorait un toast affiché dans les deux secondes suivant le dernier qu'il avait montré pour votre mod, et la ligne du log de débogage pour le toast ignoré indiquait within 2000ms of the last; dropped.

La bande affiche plugin panel hidden

La bande est réduite. Elle se réduit lorsque vous appuyez sur Ctrl+X puis Ctrl+A, ou sur les touches que vous avez associées à la place, et en rendu plein écran lorsque vous cliquez sur le [-] de sa première ligne. Elle reste réduite jusqu'à ce que vous la développiez ou redémarriez Claude Code, et pendant ce temps aucun raccourci clavier ni liaison action n'active de bouton qu'elle contient.

Pour développer la bande, appuyez sur les touches indiquées par la ligne, Ctrl+X puis Ctrl+A par défaut, ou en rendu plein écran cliquez sur la ligne.

Les raccourcis clavier ne font rien

Votre volet ou votre bande n'a pas le focus clavier, votre bouton se trouve dans une bande réduite, ou le dessin se trouve dans l'extension VS Code, où les boutons n'ont pas de raccourcis clavier. Appliquez la solution correspondante :

• Pas de focus clavier : appuyez sur Ctrl+X puis Tab ou, en rendu plein écran, cliquez sur le volet ou la bande. Pour que le volet prenne le focus à son ouverture, ouvrez-le avec focus: true depuis une commande.
• Le bouton se trouve dans une bande réduite : la bande affiche une ligne atténuée qui commence par ▸ plugin panel hidden. Appuyez sur les touches indiquées par la ligne, Ctrl+X puis Ctrl+A par défaut, pour la développer.
• Dans l'extension VS Code : cliquez sur le bouton, ou appuyez sur Enter lorsqu'il a le focus

Un dessin fonctionne dans le terminal mais pas dans l'application Desktop ni dans VS Code

Soit cette application ne dessine pas le point de rendu ou l'élément, soit la session est de celles où l'extension VS Code ne dessine rien pour les mods. Les autres hooks du mod s'exécutent toujours. Vérifiez les causes suivantes :

• Le point de rendu ou l'élément n'est pas dessiné dans cette application : recherchez votre point de rendu dans le tableau des points de rendu et vos éléments dans le tableau des éléments. Pour un élément que l'application ne prend pas en charge, vérifiez e.surface dans le hook et renvoyez un arbre que l'application peut dessiner.
• L'extension VS Code est antérieure à la version 2.1.299 : le panneau de chat dessine pour les mods à partir de la version de l'extension 2.1.299. Vérifiez la version dans la vue Extensions de VS Code et mettez l'extension à jour depuis celle-ci.
• L'extension est antérieure à la version 2.1.304 et la session ne récupère pas les feature flags : mettez l'extension à jour, ou exécutez plutôt claude dans le terminal intégré de VS Code. Les sessions sur Amazon Bedrock, Agent Platform de Google Cloud ou Microsoft Foundry ignorent cette récupération. Pour les autres cas où elle est ignorée, comme une session de passerelle des applications Claude, consultez Fonctionnalités nécessitant la récupération des feature flags.

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.

Une clé renvoyée par votre hook settings.read ne prend pas effet

Si vous renvoyez des règles de permission ou env lors de la lecture propre de Claude Code, les règles ne sont pas vérifiées lors des appels d'outils et les entrées env ne deviennent pas des variables d'environnement. Utilisez un fichier de paramètres pour les deux, ou $.env.set pour env.

Pour une autre clé, vérifiez quels mods reçoivent settings.read et à partir de quelle version, puis recherchez settings.read dans le log de débogage et repérez l'une de ces lignes :

Si aucune ligne n'explique la clé, vérifiez si les mods qui s'exécutent avant le vôtre ont un hook settings.read qui modifie la clé. Désactivez ce mod, ou demandez à l'administrateur de votre organisation de le faire. Si aucun hook ne la modifie, définissez la clé dans un fichier de paramètres.

the answer for <key> is no value the key can hold

Cette ligne du log de débogage signifie que Claude Code a refusé la valeur renvoyée par un hook settings.read pour la clé nommée, et pour cette clé uniquement :

settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

La valeur renvoyée pour la clé nommée ne correspondait pas au schéma de cette clé, par exemple par son type ou sa plage.

• Votre valeur ne correspond pas au schéma de la clé : renvoyez-en une qu'autorise l'entrée de la clé dans la référence des paramètres.
• Votre valeur correspond : la valeur non conforme provient du hook settings.read d'un autre mod. Pour trouver ce mod, suivez les étapes pour désactiver les mods un par un. Recherchez cette ligne dans chaque nouveau log au lieu de refused to the engine.

Tant que la valeur ne correspond pas, la clé conserve la valeur fusionnée à partir des sources de paramètres avant qu'un hook ne réponde. La ligne l'appelle la valeur propre des paramètres.

settings.read: refused to the engine

Vous voyez cette ligne dans le log de débogage lorsque la lecture propre de Claude Code est refusée, et Claude Code abandonne la valeur de chaque hook. Lorsqu'un hook settings.read refuse cette lecture avec { deny: reason }, la ligne contient la raison de ce hook :

settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

Recherchez dans votre code la raison indiquée entre parenthèses :

• Votre code le contient : votre hook a refusé la lecture. Faites-lui renvoyer { value } lorsque next.origin indique la lecture propre de Claude Code.
• Votre code ne la contient pas : désactivez vos autres mods un par un. Si votre organisation a déployé un mod, demandez à son administrateur de le désactiver. Après chacun :
  1. Démarrez la session depuis votre shell avec claude --debug-file ./settings-read-2.log, suivi des flags avec lesquels elle a démarré. Utilisez un nouveau chemin à chaque fois.
  2. Recherchez refused to the engine dans ce fichier. Si la ligne y figure, désactivez le mod suivant. Sinon, le dernier mod que vous avez désactivé a refusé la lecture ; laissez-le donc désactivé.

Si la ligne persiste alors qu'il ne reste aucun autre mod, définissez les clés que votre hook renvoie dans un fichier de paramètres. Ses valeurs s'appliquent tant que la lecture est refusée.

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 gère. 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

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 fonctionnelle continue de s'exécuter jusqu'au prochain rechargement des plugins par Claude Code, par exemple lorsque vous exécutez /reload-plugins.

É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