Fehlerbehebung für ein Mod
Finden Sie heraus, warum ein Claude Code Mod nichts tut: Ordnen Sie das Symptom oder die Meldung seiner Ursache zu, schauen Sie sich Ablehnungsmeldungen an, und lesen Sie das Debug-Protokoll.
Wenn ein Modul eines Mods oder einer seiner Hooks fehlschlägt, überspringt Claude Code es und die Sitzung wird fortgesetzt, sodass ein fehlerhafter Mod wie einer aussehen kann, der nichts tut. Überprüfen Sie zunächst, was Claude Code aus Ihrem Mod gelesen hat und wo es ein Problem meldet, und suchen Sie dann das Symptom oder die Meldung, die Sie haben.
Finden Sie heraus, warum ein Mod nichts tut
Wenn ein Mod nichts tut, finden zwei Überprüfungen den Grund: was Claude Code aus den Dateien des Mods liest, und die Zeile, die es schreibt, wenn es etwas überspringt. Für das erste führen Sie in Ihrer Shell claude plugin validate mit dem Verzeichnis des Mods aus, wie in claude plugin validate ./first-mod. Es erfasst ein falsch geschriebenes Ereignis, ein fehlerhaftes Manifest und ein Modul, das Claude Code nicht lesen kann, ohne eine Sitzung zu starten.
Wenn ein Modul nicht geladen wird, ein Hook übersprungen wird oder ein anderer Mod Ihren ablehnt, schreibt Claude Code eine Zeile, die Ihren Mod benennt. Wo Sie diese Zeile lesen, hängt von der Sitzung ab:
- Eine Sitzung, die ein Plugin-Verzeichnis neu lädt: eine schwache Zeile im Transkript. Das ist eine interaktive Sitzung, die Sie mit
--plugin-dirgestartet haben, oder eine, in der Sie das Neuladen aktiviert haben für Mods, die Claude geschrieben hat. - Jede andere interaktive Sitzung, wie eine, die einen Mod ausführt, den Sie von einem Marketplace installiert haben: das Debug-Protokoll nur. Um eines zu erhalten, starten Sie die Sitzung mit
claude --debug. - Ein
claude -pLauf mit--plugin-dir: stderr, im Standard-Textausgabeformat. Eine Ablehnung durch einen anderen Mod geht nur ins Debug-Protokoll.
Überprüfen Sie, ob Mods geladen werden können
Um zu überprüfen, ob Ihre Einrichtung Mods überhaupt laden kann, ohne einen zu installieren, führen Sie claude plugin test in Ihrer Shell aus, von einem Verzeichnis, das keinen Mod enthält. Sie benötigen keine Sitzung. Die Meldung, die es ausgibt, teilt Ihnen den Status mit:
| Meldung enthält | Was es bedeutet |
|---|---|
no hooks module to load |
Mods können geladen werden. Der Befehl hat keinen Mod zum Testen in diesem Verzeichnis gefunden. |
hooks modules are turned off here |
Eine Einstellung hält Ihre Mods aus: disableAllHooks in Ihren eigenen Einstellungen oder die Richtlinie Ihrer Organisation |
hooks modules are turned off in this process |
Anthropic hat installierte Mods remote ausgeschaltet. Keine Einstellung auf Ihrem Computer schaltet sie wieder ein. |
Eine Organisation kann auch allowManagedModsOnly setzen, um nur ihre eigenen Mods zuzulassen, was dieser Befehl nicht meldet. In diesem Fall wird ein Mod, den Sie installieren, nicht geladen, und eine Meldung erklärt warum.
Der Mod wird nicht geladen
Nichts, das der Mod hinzufügt, wird angezeigt: kein Befehl, keine Zeichnung und keine Verhaltensänderung.
Ihre Version ist älter als 2.1.287
claude --version gibt eine Version älter als 2.1.287 aus. Ihre Version stammt von vor der Zeit, als Mods standardmäßig aktiviert waren.
Aktualisieren Sie Claude Code.
Die `mods active` Zeile benennt den Mod nicht
Nichts, das der Mod hinzufügt, wird angezeigt, und die mods active Zeile in /plugin benennt ihn nicht. Das Hooks-Modul wurde nicht geladen. Wenn Claude Code es ablehnte, hat das Debug-Protokoll eine Zeile, die mit hooks module, dem Namen des Mods und not loaded: beginnt, wie in hooks module first-mod@inline not loaded: disableAllHooks in managed settings für einen Mod, der mit --plugin-dir geladen wurde.
Lesen Sie den Grund nach dem Doppelpunkt. Der Abschnitt Ablehnungsmeldungen listet jeden auf. Wenn das Protokoll keine solche Zeile hat, arbeiten Sie die anderen Einträge in dieser Gruppe durch.
Ein `claude -p` Lauf gibt `hooks module not loaded` aus
Die Zeile beginnt mit dem Namen des Mods und geht zu stderr. Das Hooks-Modul wurde abgelehnt. Ein nicht-interaktiver Lauf hat kein Transkript, daher geht die Meldung zu stderr.
Lesen Sie den Grund nach dem Doppelpunkt. Der Abschnitt Ablehnungsmeldungen listet jeden auf.
Ablehnungsmeldungen
Jede dieser folgt hooks module, dem Namen des Mods und not loaded: im Debug-Protokoll.
| Meldung beginnt mit | Was es bedeutet |
|---|---|
hooks modules are turned off for installed plugins in this process |
Anthropic hat installierte Mods remote ausgeschaltet. Keine Einstellung auf Ihrem Computer schaltet sie wieder ein. |
disableAllHooks in managed settings |
Ihre Organisation hat Hooks von installierten Plugins ausgeschaltet |
only managed plugins and built-in plugins run |
allowManagedHooksOnly ist gesetzt, oder disableAllHooks ist in einer Einstellungsdatei außer verwalteten Einstellungen gesetzt |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Sie haben Claude Code mit --bare gestartet |
another plugin of that name loads first |
Zwei Plugins teilen sich einen Namen. Das verwaltete oder das zuerst geladene wird verwendet. |
Meldungen vom integrierten Guard
Auf einem Computer mit verwalteten Einstellungen oder für einen Benutzer, der mit einem Team- oder Enterprise-Plan angemeldet ist, kann der integrierte Guard einen Mod oder eine seiner Antworten ablehnen. Jede Meldung benennt die Option, die der Administrator Ihrer Organisation setzt, um die Regel zu ändern.
| Meldung enthält | Was es bedeutet | Wo es angezeigt wird |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
Ihre Organisation erlaubt nur ihre eigenen Mods, daher wurde Ihrer nicht geladen | Das Debug-Protokoll und das Transkript in einer Sitzung, die ein Plugin-Verzeichnis neu lädt |
tried to lift a deny rule in your settings |
Der tool.check Hook Ihres Mods genehmigte einen Aufruf, den eine deny Regel ablehnt. Der Aufruf bleibt abgelehnt. |
Das Transkript und das Debug-Protokoll, einmal für jeden Mod in einer Sitzung. In einem claude -p Lauf nur das Debug-Protokoll. |
the deny rules in your settings could not be checked for this call, so it is refused |
Der Guard ist fehlgeschlagen, während er einen Aufruf überprüfte, den ein Mod genehmigte, daher lehnte er den Aufruf ab | Der Grund, den Claude für den abgelehnten Aufruf liest |
`validate` besteht und listet keine `hooks` Zeile auf
hooks/hooks.json hat keinen modules Schlüssel, oder der Schlüssel ist falsch geschrieben.
Fügen Sie "modules": ["./register.js"] hinzu.
`hooks module did not load`
Die Zeile beginnt mit dem Namen des Mods, dann hooks module did not load: und ein Grund, der die Datei und Zeile angibt, wenn das Problem in Ihrem Code ist. Claude Code konnte das Modul nicht laden, zum Beispiel weil sein Code auf oberster Ebene geworfen wurde.
Beheben Sie den Fehler, den der Grund benennt.
`options do not fit plugin.json userConfig`
Die Zeile beginnt mit dem Namen des Mods, dann hooks module did not load: options do not fit plugin.json userConfig: und ein Grund. Eine Option passt nicht zu ihrem userConfig Feld, wie eine Zahl über dem max Feld, oder ein erforderliches Feld hat keinen Wert.
Setzen oder ändern Sie den Wert. Das Ende der Zeile benennt seinen pluginConfigs Eintrag in settings.json.
Kein Mod wird in einem Verzeichnis geladen, das Sie zum ersten Mal geöffnet haben
Sie haben die Vertrauensaufforderung für das Verzeichnis nicht beantwortet.
Starten Sie eine interaktive Sitzung in diesem Verzeichnis mit claude, und akzeptieren Sie die Vertrauensaufforderung, die sie öffnet.
Kein installiertes Plugin wird überhaupt geladen
Sie haben Claude Code mit --safe-mode gestartet.
Starten Sie ohne das Flag.
Ein Hook wird übersprungen oder ein Mod wird entladen
Der Mod wurde geladen, und dann übersprungen Claude Code einen seiner Hooks oder entlud ihn.
`hook skipped`
Die Zeile benennt den Mod und das Ereignis, dann sagt hook skipped: und ein Grund, wie in first-mod: tool.call hook skipped: threw Error: boom. Ein Hook warf, lief über sein 10-Sekunden-Zeitlimit hinaus, oder gab ein Ergebnis der falschen Form zurück. Die Zeile wird einmal für jedes Ereignis und jede Art von Fehler angezeigt, bis der Mod neu geladen wird.
Beheben Sie den Fehler. Das Debug-Protokoll hat eine Zeile für jedes Vorkommen.
`it crashed the hooks worker`
Die Zeile beginnt mit dem Namen des Mods, wie in first-mod was unloaded: it crashed the hooks worker. Installierte Mods teilen sich einen Worker-Thread. Der Worker hat nicht mehr reagiert oder ist abgestürzt, und Claude Code hat das auf diesen Mod zurückgeführt und ihn entladen. Ein Hook, der den Thread blockiert, wie eine Schleife, die nie erwartet, ist eine Ursache.
Beheben Sie den Hook.
`mods that run in the hooks worker are off for this session`
Die Zeile liest hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Der Worker ist dreimal gestoppt worden und Claude Code konnte die Stopps nicht auf einen Mod zurückführen, daher entlud es jeden Mod, der nicht integriert ist, einschließlich Mods, die Ihre Organisation installiert. Diese Zeile erreicht das Transkript in jeder interaktiven Sitzung.
Führen Sie /reload-plugins aus, um sie wieder zu laden.
Ein Tool-Aufruf wird abgelehnt
Der Mod wurde geladen und seine Hooks laufen, und ein Tool-Aufruf, den er berührte, wird abgelehnt.
`a hook changed this call's input after the model wrote it`
Im Auto-Modus gibt ein abgelehnter Tool-Aufruf diesen Grund an. Ein Hook hat die Eingabe des Tool-Aufrufs geändert, nachdem der serverseitige Klassifizierer ihn überprüft hat, daher deckt diese Überprüfung nicht ab, was ausgeführt würde. Der Hook kann ein tool.call oder turn.step Hook eines Mods sein, oder ein PreToolUse Einstellungs-Hook. Die Meldung sagt nicht, welcher.
Die Meldung teilt Claude mit, den Aufruf einmal mehr wie aufgezeichnet auszugeben. Wenn dieser auch abgelehnt wird, ändert der Hook die Eingabe jedes Mal, daher schalten Sie den Mod oder Hook aus, oder verlassen Sie den Auto-Modus und genehmigen Sie den Aufruf selbst.
Eine Meldung über die Deny-Regeln in Ihren Einstellungen
tried to lift a deny rule in your settings und the deny rules in your settings could not be checked for this call, so it is refused kommen beide vom integrierten Guard.
Schauen Sie sie in Meldungen vom integrierten Guard nach.
Eine Zeichnung wird nicht angezeigt oder reagiert nicht
Der Mod wurde geladen, und sein Bereich, Band oder Steuerelemente verhalten sich nicht wie erwartet.
Ein Bereich oder Band ist leer oder zeigt den üblichen Inhalt von Claude Code
Der Baum, den Ihr Hook zurückgab, wurde nicht validiert. Mit --plugin-dir sagt das Transkript ui.render (Pane) refused: mit dem Grund, wie in first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Das Debug-Protokoll hat a hook returned a tree that does not validate mit dem gleichen Grund.
Lesen Sie den Grund auf dieser Zeile. Häufige Ursachen sind eine Eigenschaft, die das Element nicht annimmt, und ein Element, das die App nicht hat.
`$.ui.open` läuft und kein Bereich wird angezeigt
Der Aufruf kam nicht von etwas, das der Benutzer tat, und das Terminal ist schmaler als 144 Spalten.
Öffnen Sie den Bereich von einem Befehl oder einer Schaltfläche, oder überprüfen Sie das isPlaced Ergebnis des Aufrufs. Siehe Öffnen Sie einen Bereich zur richtigen Zeit.
Hotkeys tun nichts
Ihr Bereich hat keinen Tastaturfokus.
Drücken Sie Strg+X und dann Tab, oder klicken Sie auf den Bereich. Öffnen Sie ihn mit focus: true von einem Befehl.
Eine Zeichnung funktioniert im Terminal und nicht in der Desktop-App
Die Website oder das Element ist dort nicht verfügbar.
Überprüfen Sie die Render-Websites und Elemente Tabellen.
Eine Bearbeitung oder ein Wert geht verloren
Der Mod läuft, und eine Änderung, die Sie vorgenommen haben, oder ein Wert, den er beibehielt, ist nicht vorhanden.
Ihre Bearbeitungen werden nicht wirksam
Sie bearbeiten ein Plugin, das Sie installiert haben. Claude Code führt die zwischengespeicherte Kopie für die installierte Version aus.
Entwickeln Sie mit --plugin-dir auf Ihre Arbeitskopie, wie in claude --plugin-dir ./first-mod, die beim Speichern neu lädt.
Ein Wert wird zurückgesetzt, wenn das Modul neu geladen wird
Variablen auf Modulebene werden bei jedem Neuladen neu initialisiert.
Behalten Sie den Wert in $.state oder $.store.
Ein Wert wird nach `/clear`, `/resume` oder `/branch` zurückgesetzt
Ein Wert wird zurückgesetzt, oder ein gespeicherter Wert wird durch seinen Standard ersetzt. Jeder dieser Befehle setzt $.state auf seine Standards zurück, und session.start wird nicht erneut ausgelöst.
Laden Sie den gespeicherten Wert nach /clear erneut in einem classic.SessionStart Hook.
Lesen Sie das Debug-Protokoll
Das Debug-Protokoll hat eine Zeile für jedes Modul, das Claude Code lädt oder ablehnt, jeden Hook, der fehlschlägt, und jedes Ergebnis, das es ablehnt, daher ist es der Ort, an dem man nachschaut, wenn das Transkript nichts zeigt. Um eines zu schreiben, starten Sie Claude Code in Ihrer Shell mit --debug, oder mit --debug-file <path>, um zu wählen, wo es geht:
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
Folgen Sie in einem anderen Terminal der Datei und filtern Sie nach dem Namen Ihres Mods:
tail -f ./mod-debug.log | grep first-mod
Ein Mod, der geladen wurde, hat eine Zeile, die ihn benennt und die Ereignisse auflistet, die er verbindet. Ein Mod, der mit --plugin-dir geladen wurde, wird unter seinem Namen gefolgt von @inline angezeigt:
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
Eine Zeichnung, die nicht validiert wurde, zählt als abgelehntes Ergebnis und erhält auch eine Zeile. Um Ihre eigenen Zeilen im Protokoll zu schreiben, rufen Sie $.ui.log mit einem zweiten Argument auf, wie in $.ui.log('message', { to: 'debug' }). Ohne das zweite Argument fügt $.ui.log eine schwache Zeile zum Transkript hinzu.
Während Sie einen Mod bearbeiten, der mit --plugin-dir geladen wurde, zeigt das Transkript eine Zeile für jedes Neuladen, die den Mod benennt und seine Hooks auflistet. Wenn ein Speichern das Modul bricht, sagt die Zeile reload failed, the previous version stays loaded: mit dem Grund, und die letzte funktionierende Version läuft weiter.
Nächste Schritte
- Testen Sie einen Mod: Fangen Sie Probleme ab, bevor sie eine Sitzung erreichen
- Fehlerbehebung für Plugins: Probleme mit der Installation und dem Laden eines Plugins, die nicht spezifisch für Mods sind