SpyBara
Go Premium

plugins/mods/troubleshoot.md 2026-10-01 23:59 UTC to 2026-10-02 19:58 UTC

This page contains 94 additions and 92 deletions.

2026
Thu 1 23:59 Fri 2 19:58

Fehlerbehebung bei einem Mod

Finden Sie heraus, warum ein Claude Code-Mod nichts bewirkt: Ordnen Sie das Symptom oder die Meldung der Ursache zu, schlagen Sie Ablehnungsmeldungen nach und lesen Sie das Debug-Log.

Wenn das Modul eines Mods oder einer seiner Hooks fehlschlägt, überspringt Claude Code es und die Sitzung wird fortgesetzt. Ein fehlerhafter Mod kann daher wie einer aussehen, der nichts bewirkt. Prüfen Sie zunächst, was Claude Code aus Ihrem Mod gelesen hat und wo es ein Problem meldet. Suchen Sie dann das Symptom oder die Meldung, die bei Ihnen auftritt.

Herausfinden, warum ein Mod nichts bewirkt

Wenn ein Mod nichts bewirkt, prüfen Sie, was Claude Code aus den Dateien des Mods liest, und die Zeile, die es schreibt, wenn es etwas überspringt. Für Ersteres führen Sie in Ihrer Shell claude plugin validate mit dem Verzeichnis des Mods aus, etwa claude plugin validate ./first-mod. Der Befehl erkennt ein falsch geschriebenes Event, 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 Mod ablehnt, schreibt Claude Code eine Zeile, die Ihren Mod nennt. Wo Sie diese Zeile lesen, hängt von der Sitzung ab:

  • Eine Sitzung, die ein Plugin-Verzeichnis per Hot Reload neu lädt: eine abgeblendete Zeile im Transkript. Das ist eine interaktive Sitzung, die Sie mit --plugin-dir gestartet haben, oder eine, in der Sie für von Claude geschriebene Mods Hot Reloading aktiviert haben.
  • Jede andere interaktive Sitzung, etwa eine, die einen aus einem Marketplace installierten Mod ausführt: ausschließlich das Debug-Log. Um eines zu erhalten, starten Sie die Sitzung mit claude --debug.
  • Ein claude -p-Lauf mit --plugin-dir: stderr, im standardmäßigen Textausgabeformat. Eine Ablehnung durch einen anderen Mod wird ausschließlich in das Debug-Log geschrieben.

Prüfen, ob Mods geladen werden können

Um zu prüfen, ob Ihre Konfiguration das Laden von Mods überhaupt zulässt, ohne einen zu installieren, führen Sie claude plugin test in Ihrer Shell aus, und zwar in einem Verzeichnis, das keinen Mod enthält. Sie benötigen keine Sitzung. Die ausgegebene Meldung zeigt Ihnen den Status:

Meldung enthält Bedeutung
no hooks module to load Mods können geladen werden. Der Befehl hat in diesem Verzeichnis keinen Mod zum Testen gefunden.
hooks modules are turned off here Eine Einstellung blockiert Ihre Mods: disableAllHooks in Ihren eigenen Einstellungen oder die Richtlinie Ihrer Organisation
hooks modules are turned off in this process Anthropic hat installierte Mods aus der Ferne ausgeschaltet. Keine Einstellung auf Ihrem Rechner schaltet sie wieder ein.

Eine Organisation kann außerdem allowManagedModsOnly setzen, um nur ihre eigenen Mods zuzulassen. Dies meldet dieser Befehl nicht. In diesem Fall wird ein von Ihnen installierter Mod nicht geladen, und eine Meldung erklärt den Grund.

Der Mod wird nicht geladen

Nichts, was der Mod hinzufügt, erscheint: kein Befehl, keine Darstellung und keine Verhaltensänderung.

Ihre Version ist älter als 2.1.287

claude --version gibt eine Version aus, die älter als 2.1.287 ist. Ihre Version stammt aus der Zeit, bevor Mods standardmäßig aktiviert waren.

Aktualisieren Sie Claude Code.

Die Zeile `mods active` nennt den Mod nicht

Nichts, was der Mod hinzufügt, erscheint, und die Zeile mods active in /plugin nennt ihn nicht. Das Hooks-Modul wurde nicht geladen. Wenn Claude Code es abgelehnt hat, enthält das Debug-Log eine Zeile, die mit hooks module, dem Namen des Mods und not loaded: beginnt, etwa 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 führt jeden davon auf. Wenn das Log keine solche Zeile enthält, arbeiten Sie die anderen Einträge in dieser Gruppe durch.

Einige Einstellungen stoppen einen Mod und lassen den Rest seines Plugins funktionsfähig. Mods ein- oder ausschalten nennt sie.

Ein `claude -p`-Lauf gibt `hooks module not loaded` aus

Die Zeile beginnt mit dem Namen des Mods und wird an stderr ausgegeben. Das Hooks-Modul wurde abgelehnt. Ein nicht interaktiver Lauf hat kein Transkript, daher wird die Meldung an stderr ausgegeben.

Lesen Sie den Grund nach dem Doppelpunkt. Der Abschnitt Ablehnungsmeldungen führt jeden davon auf.

Ablehnungsmeldungen

Jede dieser Meldungen folgt im Debug-Log auf hooks module, den Namen des Mods und not loaded:.

Meldung beginnt mit Bedeutung
hooks modules are turned off for installed plugins in this process Anthropic hat installierte Mods aus der Ferne ausgeschaltet. Keine Einstellung auf Ihrem Rechner schaltet sie wieder ein.
disableAllHooks in managed settings Ihre Organisation hat Hooks aus installierten Plugins ausgeschaltet
only managed plugins and built-in plugins run allowManagedHooksOnly ist gesetzt, oder disableAllHooks ist in einer anderen Einstellungsdatei als den 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 haben denselben Namen. Das verwaltete oder das zuerst geladene wird verwendet.

Meldungen des integrierten Wächters

Auf einem Rechner mit verwalteten Einstellungen oder für einen Benutzer, der mit einem Team- oder Enterprise-Plan angemeldet ist, kann der integrierte Wächter einen Mod oder eine seiner Antworten ablehnen. Jede Meldung nennt die Option, die der Administrator Ihrer Organisation setzt, um die Regel zu ändern.

Meldung enthält Bedeutung Wo sie erscheint
mods are limited to your organization's by policy (allowManagedModsOnly) Ihre Organisation erlaubt nur ihre eigenen Mods, daher wurde Ihrer nicht geladen Im Debug-Log und im Transkript in einer Sitzung, die ein Plugin-Verzeichnis per Hot-Reload neu lädt
tried to lift a deny rule in your settings Der tool.check-Hook Ihres Mods hat einen Aufruf genehmigt, den eine deny-Regel ablehnt. Der Aufruf bleibt abgelehnt. Im Transkript und im Debug-Log, einmal pro Mod in einer Sitzung. In einem claude -p-Lauf nur im Debug-Log.
the deny rules in your settings could not be checked for this call, so it is refused Der Wächter ist beim Prüfen eines Aufrufs, den ein Mod genehmigt hat, fehlgeschlagen und hat den Aufruf daher abgelehnt Im Grund, den Claude für den abgelehnten Aufruf liest

`validate` ist erfolgreich und listet keine `hooks`-Zeile auf

hooks/hooks.json hat keinen Schlüssel modules, 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, gefolgt von hooks module did not load: und einem Grund, der die Datei und Zeile angibt, wenn das Problem in Ihrem Code liegt. Claude Code konnte das Modul nicht laden, zum Beispiel weil sein Code auf oberster Ebene einen Fehler ausgelöst hat.

Beheben Sie den Fehler, den der Grund nennt.

`options do not fit plugin.json userConfig`

Die Zeile beginnt mit dem Namen des Mods, gefolgt von hooks module did not load: options do not fit plugin.json userConfig: und einem Grund. Eine Option besteht die Validierung gegen ihr userConfig-Feld nicht, etwa eine Zahl über dem max des Felds, oder ein Pflichtfeld hat keinen Wert.

Setzen oder ändern Sie den Wert. Das Ende der Zeile nennt den zugehörigen pluginConfigs-Eintrag in settings.json.

In einem Verzeichnis, das Sie zum ersten Mal geöffnet haben, wird kein Mod geladen

Sie haben die Vertrauensabfrage für das Verzeichnis nicht beantwortet.

Starten Sie mit claude eine interaktive Sitzung in diesem Verzeichnis und akzeptieren Sie die Vertrauensabfrage, mit der sie beginnt.

Überhaupt kein installiertes Plugin wird 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 anschließend hat Claude Code einen seiner Hooks übersprungen oder den Mod entladen.

`hook skipped`

Die Zeile nennt den Mod und das Event, dann folgt hook skipped: und ein Grund, wie in first-mod: tool.call hook skipped: threw Error: boom. Ein Hook hat einen Fehler ausgelöst, sein Zeitlimit überschritten oder ein Ergebnis mit falscher Struktur zurückgegeben. Die Zeile erscheint einmal für jedes Event und jede Art von Fehler, bis der Mod neu geladen wird.

Beheben Sie den Fehler. Das Debug-Log enthält eine Zeile für jedes Auftreten.

`no command.run hook answered it`

Sie führen einen Befehl aus, den Ihr Mod hinzugefügt hat, und die Antwort nennt den Mod und den Befehl, wie in first-mod registered /tally but no command.run hook answered it, und fordert Sie dann auf, einen Hook hinzuzufügen. Claude Code gibt diese Antwort aus, wenn der Befehl das Ende der Kette ohne Antwort erreicht, was in zwei Fällen geschieht:

  • Kein Hook hat den Befehl beantwortet: Das Modul hat keinen command.run-Hook, der Filter des Hooks nennt einen anderen Befehl, oder der Hook hat next(e) zurückgegeben
  • Claude Code hat den Hook übersprungen: hook skipped listet die Gründe auf. Die Übergabe von focus: false an $.ui.open ist eine Möglichkeit, in diese Situation zu geraten.

Wenn das Modul den in der Antwort beschriebenen Hook bereits enthält, suchen Sie nach einer hook skipped-Zeile, die command.run nennt und den Grund angibt. Ein Test, der den Befehl ausführt, schlägt mit demselben Grund fehl.

`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 dies auf diesen Mod zurückgeführt und ihn entladen. Ein Hook, der den Thread blockiert, etwa eine Schleife, die nie await aufruft, ist eine mögliche Ursache.

Beheben Sie den Hook.

`mods that run in the hooks worker are off for this session`

Die Zeile lautet hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Der Worker ist dreimal ausgefallen, und Claude Code konnte die Ausfälle nicht auf einen einzelnen Mod zurückführen. Daher wurden alle Mods entladen, die nicht integriert sind, einschließlich der Mods, die Ihre Organisation installiert. Diese Zeile erscheint in jeder interaktiven Sitzung im Transkript.

Führen Sie /reload-plugins aus, um sie erneut zu laden.

Ein Tool-Aufruf wird abgelehnt

Der Mod wurde geladen und seine Hooks laufen, und ein Tool-Aufruf, den er verändert hat, wird abgelehnt.

`a hook changed this call's input after the model wrote it`

Im Auto-Modus liefert ein abgelehnter Tool-Aufruf diese Begründung. Ein Hook hat die Eingabe des Tool-Aufrufs geändert, nachdem der serverseitige Klassifikator sie geprüft hatte, sodass diese Prüfung nicht abdeckt, was ausgeführt würde. Der Hook kann ein tool.call- oder turn.step-Hook eines Mods oder ein PreToolUse-Einstellungs-Hook sein. Die Meldung gibt nicht an, welcher.

Die Meldung weist Claude an, den Aufruf noch einmal so wie aufgezeichnet auszuführen. Wird auch dieser abgelehnt, ändert der Hook die Eingabe jedes Mal. Schalten Sie dann den Mod oder Hook aus, oder verlassen Sie den Auto-Modus und genehmigen Sie den Aufruf selbst.

Eine Meldung zu den Ablehnungsregeln 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 stammen beide vom integrierten Wächter.

Schlagen Sie sie unter Meldungen des integrierten Wächters nach.

Eine Darstellung erscheint nicht oder reagiert nicht

Der Mod wurde geladen, aber sein Bereich, sein Band oder seine 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ückgegeben hat, wurde nicht validiert. Mit --plugin-dir zeigt das Transkript ui.render (Pane) refused: zusammen mit dem Grund an, etwa 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-Log enthält a hook returned a tree that does not validate mit demselben Grund.

Lesen Sie den Grund in dieser Zeile. Häufige Ursachen sind eine Prop, die das Element nicht akzeptiert, und ein Element, das die App nicht hat.

`$.ui.open` wird ausgeführt, aber kein Bereich erscheint

Der Aufruf wurde nicht durch eine Aktion des Benutzers ausgelöst, und das Terminal ist schmaler als die Breite, die dieser Bereich benötigt.

Öffnen Sie den Bereich über einen Befehl oder eine Schaltfläche, oder prüfen Sie das Ergebnis isPlaced des Aufrufs. Siehe Einen Bereich zum richtigen Zeitpunkt öffnen.

Tastenkürzel bewirken nichts

Ihr Bereich hat nicht den Tastaturfokus.

Drücken Sie Strg+X und dann Tab, oder klicken Sie auf den Bereich. Öffnen Sie ihn über einen Befehl mit focus: true.

Eine Darstellung funktioniert im Terminal, aber nicht in der Desktop-App

Die Stelle oder das Element ist dort nicht verfügbar.

Prüfen Sie die Tabellen Render-Stellen und Elemente.

Eine Änderung oder ein Wert geht verloren

Der Mod läuft, aber eine Änderung, die Sie vorgenommen haben, oder ein Wert, den er gespeichert hat, ist nicht vorhanden.

Ihre Änderungen werden nicht wirksam

Sie bearbeiten ein Plugin, das Sie installiert haben. Claude Code führt die zwischengespeicherte Kopie der installierten Version aus.

Entwickeln Sie mit --plugin-dir, das auf Ihre Arbeitskopie verweist, wie in claude --plugin-dir ./first-mod, das 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.

Speichern 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 Standardwert ersetzt. Jeder dieser Befehle setzt $.state auf die Standardwerte zurück, und session.start wird nicht erneut ausgelöst.

Laden Sie den gespeicherten Wert erneut in einem classic.SessionStart-Hook.

Das Debug-Log lesen

Das Debug-Log enthält eine Zeile für jedes Modul, das Claude Code lädt oder ablehnt, für jeden Hook, der fehlschlägt, und für jedes Ergebnis, das es ablehnt. Dort sollten Sie also nachsehen, wenn das Transkript nichts anzeigt. Um eines zu schreiben, starten Sie Claude Code in Ihrer Shell mit --debug oder mit --debug-file <path>, um festzulegen, wohin es geschrieben wird:

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

Verfolgen Sie die Datei in einem anderen Terminal und filtern Sie nach dem Namen Ihres Mods:

tail -f ./mod-debug.log | grep first-mod

Für einen Mod, der geladen wurde, gibt es eine Zeile, die ihn benennt und die Events auflistet, die er verarbeitet. Ein mit --plugin-dir geladener Mod erscheint unter seinem Namen, gefolgt von @inline:

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

Eine Zeichnung, die die Validierung nicht bestanden hat, gilt als abgelehntes Ergebnis und erhält ebenfalls eine Zeile. Um eigene Zeilen in das Log 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 dem Transkript eine abgeblendete Zeile hinzu.

Während Sie einen mit --plugin-dir geladenen Mod bearbeiten, zeigt das Transkript für jedes Neuladen eine Zeile an, die den Mod benennt und seine Hooks auflistet. Wenn ein Speichervorgang das Modul beschädigt, lautet die Zeile reload failed, the previous version stays loaded: mit dem Grund, und die letzte funktionierende Version läuft weiter.

Nächste Schritte