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 für von Claude geschriebene Mods Hot Reloading aktiviert ist.
• 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:

Eine Organisation kann außerdem allowManagedModsOnly setzen, um nur ihre eigenen Mods zuzulassen. Dies meldet dieser Befehl nicht. In diesem Fall lehnt Claude Code einen von Ihnen installierten Mod ab, 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 zu alt

Siehe welche Version Sie verwenden sollten und wie Sie Ihre Version prüfen.

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

Meldungen des integrierten Wächters

Wo der integrierte Wächter geladen wird, kann er einen Mod oder eine seiner Antworten ablehnen. Jede Meldung nennt die Option, die der Administrator Ihrer Organisation setzt, um die Regel zu ändern.

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.

Wenn der Grund mit ; the version loaded before is unloaded endet, läuft derzeit keine Version des Mods. Sobald Sie den Fehler behoben haben, führen Sie /reload-plugins in der Sitzung aus, um den Mod erneut zu laden. Wenn Sie den Mod installiert und nicht selbst geschrieben haben, bitten Sie dessen Autor, den Fehler zu beheben.

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.

code nested too deep to scan: more than 2000 scopes

Die Zeile beginnt mit dem Namen des Mods, gefolgt von hooks module did not load:, der Datei und code nested too deep to scan: more than 2000 scopes. Eine Datei in einem Hooks-Modul kann Gültigkeitsbereiche wie Funktionen, Blöcke und Schleifen nicht tiefer als 2.000 Ebenen verschachteln. claude plugin validate meldet denselben Grund.

Schreiben Sie den Code so um, dass seine Gültigkeitsbereiche weniger tief verschachtelt sind.

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

Code im Hooks-Modul ist zu tief verschachtelt, oder seine Kette von Importen ist zu lang, als dass Claude Code ihn laden könnte. Die Zeile beginnt mit dem Namen des Mods und hooks module did not load:, gefolgt vom Namen einer Datei und diesem Grund.

Durchsuchen Sie diese Datei und die Dateien, die über ihre Importe erreicht werden, nach dem am tiefsten verschachtelten Teil und schreiben Sie ihn so um, dass er weniger tief verschachtelt ist, oder verkürzen Sie die Kette von Importen. Wenn Sie den Mod nicht selbst geschrieben haben, bitten Sie dessen Autor, ihn zu beheben.

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

Code in einer Datei des Hooks-Moduls ist so tief verschachtelt, dass Claude Code beim Lesen der Stack ausgegangen ist. Die Zeile beginnt mit dem Namen des Mods und hooks module did not load:, gefolgt vom Namen dieser Datei und einem dieser Gründe:

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

Der Grund enthält keine Zeilennummer und gibt nicht an, welche Art von Code verschachtelt ist. Durchsuchen Sie die Datei daher selbst nach ihrem am tiefsten verschachtelten Teil. Schreiben Sie diesen Teil so um, dass er weniger tief verschachtelt ist. Wenn Sie den Mod installiert und nicht selbst geschrieben haben, bitten Sie dessen Autor darum.

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.

Claude Code fragt nicht mehr, ob Hot-Reloading aktiviert werden soll

Claude schreibt in einer interaktiven Sitzung einen Mod, nichts wird geladen, und Claude Code fragt nicht erneut, ob Hot-Reloading aktiviert werden soll. Wenn die Frage dreimal endet, ohne dass eine Antwort ausgewählt wurde, bleibt Hot-Reloading ausgeschaltet. Die Frage endet zum Beispiel auf diese Weise, wenn Sie askUserQuestionTimeout festlegen und die Zeit abläuft, bevor Sie antworten. Diese Einstellung gilt hier, weil Claude Code im selben Fragedialog fragt, den AskUserQuestion verwendet. Eine Frage, die Sie selbst schließen, zählt nicht zu den dreien.

Um den Mod auszuführen, kopieren Sie sein Verzeichnis aus dem Mods-Ordner und starten Sie dann in Ihrer Shell eine neue Sitzung mit --plugin-dir, etwa claude --plugin-dir ~/mods/git-branch.

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.

its session.start ran again in a fresh copy

Die Zeile beginnt mit dem Namen des Mods und nennt einen Aufruf von $.prompt.submit, $.command.run oder $.agent.spawn, wie in 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 hat das Modul des Mods erneut geladen, zum Beispiel nachdem der Hooks-Worker abgestürzt war und ersetzt wurde, und der session.start-Hook der neuen Kopie wurde ausgeführt. Der in der Zeile genannte Aufruf wurde mit dem Ergebnis seiner ersten Ausführung aufgelöst, statt erneut ausgeführt zu werden, sodass Ihr Mod den Prompt nicht zweimal sendet, den Befehl nicht zweimal ausführt und den Subagenten nicht zweimal startet. Der Rest des Hooks wurde wie gewohnt ausgeführt.

Es gibt nichts zu beheben.

Vor v2.1.292 wurde der Aufruf ein zweites Mal ausgeführt, sodass der Prompt zweimal gesendet, der Befehl zweimal ausgeführt oder der Subagent zweimal gestartet wurde.

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

Eine Änderung an einem Mod, den Claude in dieser Sitzung geschrieben hat, konnte nicht geladen werden. Die Zeile im Transkript beginnt mit dem Namen des Mods und endet mit dem Grund:

• 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 sieht diese Zeile nicht. Fügen Sie sie daher in Ihre nächste Nachricht ein, wenn Sie Claude um eine Korrektur bitten.

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

Die Zeile beginnt mit dem Namen Ihres Mods, wie in first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed), und der Agent wird nicht registriert. Ihr Mod wurde vor dem Aufruf neu geladen oder entladen. Ein Neuladen lädt eine neue Kopie des Hooks-Moduls, und dieser Aufruf stammt aus Code, der noch in der alten Kopie ausgeführt wurde, etwa aus einem Hook, der noch nicht zurückgekehrt war.

Wenn dieser Hook die Ablehnung nicht abfängt, schlägt er fehl, und Claude Code überspringt ihn. Um den Agenten aus der Kopie zu registrieren, die geladen bleibt, führen Sie den Aufruf in Ihrem session.start-Hook aus, der nach einem Neuladen in jeder neuen Kopie erneut ausgeführt wird.

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.

[!NOTE]

In einigen interaktiven Terminal-Sitzungen und VS Code-Sitzungen liefert dieselbe Ablehnung die Begründung a hook changed this call's input after auto mode reviewed it. Der wiederholte Aufruf enthält dort die erste Änderung des Mods, und ein tool.call-Hook läuft weiterhin darauf, aber eine weitere Änderung wird verworfen. Sie müssen Ihren Mod nicht ändern, es sei denn, Claude teilt Ihnen in seiner Antwort mit, dass der Auto-Modus den Aufruf nicht prüfen konnte.

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.

Nach dem Stoppen eines Turns erscheint eine Benachrichtigung

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

Diese Benachrichtigung bedeutet, dass ein Mod, nachdem Sie den Turn gestoppt haben, zum Beispiel mit Esc, versucht hat, von sich aus mit der Arbeit zu beginnen, und Claude Code dies nicht zugelassen hat. Es muss nichts behoben werden. Nach Ihrer nächsten Nachricht können Mods wieder mit der Arbeit beginnen, und ein Teil dieser Arbeit wird von selbst wieder aufgenommen. Wenn das, was Sie vom Mod erwartet haben, nicht wieder aufgenommen wird, fordern Sie es erneut an oder führen Sie den Befehl des Mods erneut aus.

Wenn Sie den Mod geschrieben haben, lesen Sie Aufrufe und Hintergrundarbeit, nachdem der Benutzer einen Turn unterbricht.

Eine Zeichnung erscheint nicht oder reagiert nicht

Der Mod wurde geladen, und sein Bereich, Band, Toast oder seine Steuerelemente verhalten sich nicht wie erwartet.

Das Band eines anderen Mods wird angezeigt und Ihres nicht

Es gibt ein Band über dem Prompt, und alle Mods teilen es sich. Ein Mod, der vor Ihrem ausgeführt wird, ersetzt Ihr Band, wenn er einen Baum zurückgibt, der das Ergebnis von next(e) nicht enthält. Um beide Bänder anzuzeigen, ändern Sie den Hook dieses Mods oder bitten Sie dessen Autor darum:

• Die Bänder danach beibehalten: Setzen Sie das Ergebnis von await next(e) unter die Kinder einer Box in seinem Baum, wie im Tab „Band über dem Prompt“ unter Festlegen, wo gezeichnet wird
• Den Baum gültig halten: Geben Sie dieser Box oder einer Box um sie herum keine der Props width, height, minWidth, minHeight, position, top, left, right, bottom, display oder overflow

Um diesen Mod zu finden, schreiben Sie ein Debug-Log und durchsuchen Sie es nach answered ui.render without next(). Eine Zeile wie other-mod (user) answered ui.render without next() nennt einen Mod, der seinen Baum zurückgegeben hat, ohne next(e) aufzurufen. Sie nennt nicht die Render-Stelle, daher kann auch ein Mod erscheinen, der nur einen Bereich zeichnet. Ein Mod, der next(e) aufruft und das Ergebnis verwirft, erzeugt keine Zeile, prüfen Sie daher auch die Hooks vor Ihrem.

Das Band eines Mods fehlt auch, wenn der Baum, den sein eigener Hook zurückgegeben hat, nicht validiert wird; die Bänder der anderen Mods bleiben dann erhalten. Um herauszufinden, welcher Mod betroffen ist und warum, schreiben Sie ein Debug-Log und durchsuchen Sie es nach ui.render hook skipped.

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. Eine hook skipped-Zeile im Transkript oder im Debug-Log nennt Ihren Mod und den Grund, wie in dieser Zeile für eine Box in einem Bereich:

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)

Beheben Sie, was der Grund nennt. Wenn der Grund abgeschnitten ist, schreiben Sie ein Debug-Log und durchsuchen Sie es nach a hook returned a tree that does not validate, um den Rest zu lesen.

Wenn die Zeile stattdessen direkt nach dem Namen der Stelle refused: enthält, wie in ui.render (Pane) refused:, siehe Eine ui.render-Zeile enthält refused.

Eine ui.render-Zeile enthält refused

ui.render (<site>) refused: oder ui.render (<site>): the chain settled on a tree that does not validate im Debug-Log bedeutet, dass der Baum an dieser Stelle eine Größenbeschränkung überschreitet. Beide Zeilen nennen die Render-Stelle und dann den Grund, und der Grund nennt die Beschränkung.

Ändern Sie die Mods, die an dieser Stelle zeichnen, sodass ihre ui.render-Hooks kleinere Bäume zurückgeben, oder bitten Sie deren Autoren darum. Wenn die Zeile im Transkript mit hooks beginnt, hat mehr als ein geladener Mod einen ui.render-Hook für diese Stelle, prüfen Sie daher die Bäume jedes dieser Mods. Bei mehreren Mods, deren Bänder über dem Prompt zu einem Baum mit mehr als 32 Ebenen verschachtelt sind, lautet die Zeile:

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

Vor v2.1.307 meldete eine refused:-Zeile für jede Stelle jeden Baum, der nicht validiert wurde, und für Pane und AbovePrompt endete sie mit ; the engine drew its own. Beheben Sie bei diesen Versionen, was der Grund nennt.

needs a key, is drawn twice oder key each once

Ein Element in dem Baum, den Ihr ui.render-Hook zurückgibt, hat keinen gültigen key, oder zwei Elemente teilen sich einen. Suchen Sie die Meldung, die Sie erhalten haben:

• <Input> needs a key oder <Select> needs a key: Das Element hat keine key-Prop, oder sein key ist leer oder kein String, wie bei key: 3. Geben Sie ihm einen nicht leeren String als key.
• <Button> needs a key: Geben Sie der Schaltfläche einen nicht leeren String als key
• is drawn twice; each takes its own key: Zwei Elemente der in der Meldung genannten Art haben denselben key, wie in Input "size" is drawn twice; each takes its own key. Geben Sie jedem Element einen eigenen key.
• key each once von press in einem Test: Die Zeichnung enthält mehr als eine Schaltfläche mit dem übergebenen Key. Schaltflächen mit derselben Beschriftung und ohne key-Prop teilen sich diese Beschriftung als Key. Geben Sie jeder Schaltfläche einen eigenen key.

Eine ui.render-Zeile enthält threw while drawn

Die Zeile nennt die Render-Stelle, dann folgen threw while drawn: und der Fehler, wie in first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own. Claude Code ist auf diesen Fehler gestoßen, während es den Baum zeichnete, den Ihr ui.render-Hook zurückgegeben hat, oder während es die Stelle aus den props, die Ihr Hook an next übergeben hat, zeichnete. Das Ende the engine drew its own bedeutet, dass die Stelle den üblichen Inhalt von Claude Code anzeigt.

Lesen Sie den Fehler und korrigieren Sie den Wert in Ihrem Hook, der ihn verursacht hat.

Vor v2.1.289 beendete dieser Fehler in einer Transkriptzeile die Sitzung mit Claude Code exited after an unrecoverable interface error.

the module failed without a message

Ein Client ist mit einem Fehler ohne Meldung fehlgeschlagen, etwa throw new Error(). Die Zeile an seiner Stelle lautet etwa my-mod: Client client/spinner.js: the module failed without a message.

Suchen Sie das throw im Code Ihres Client und geben Sie dem Fehler eine Meldung. Die Zeile zeigt dann diese Meldung an.

Vor v2.1.289 zeigte die Zeile stattdessen Error als Grund an.

$.ui.open wird ausgeführt und es erscheint kein Bereich

Der Aufruf ging nicht auf eine Aktion des Benutzers zurück, 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.

Ein Toast erscheint nicht

Ihr Mod ruft $.ui.toast in einer interaktiven Terminal-Sitzung auf, und Sie sehen den Toast nicht. Um zu bestätigen, dass der Aufruf ausgeführt wurde, suchen Sie im Debug-Log nach einer Zeile mit dem Namen Ihres Mods und dem Text des Toasts, wie in $.ui.toast (first-mod): build finished. Prüfen Sie dann Ursachen wie diese:

• Die Zeile für den Aufruf fehlt: Suchen Sie nach einer Zeile, die angibt, warum Claude Code den Aufruf abgelehnt hat, wie in first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000.
• Ein Bereich hält Toasts zurück: Ihr Mod oder ein anderer hat holdToasts übergeben, als er den angezeigten Bereich geöffnet hat. Schließen Sie den Bereich, um das Zurückhalten zu beenden. Wenn der Bereich Ihrer ist und geöffnet bleiben soll, entfernen Sie holdToasts aus seinem $.ui.open-Aufruf und öffnen Sie den Bereich erneut.
• Der Toast befindet sich unter dem Prompt: Sehen Sie im klassischen Renderer rechts unter dem Prompt nach. Ein Toast dort ist eine Zeile, die mit dem Namen des Mods beginnt, statt eines Kastens oben rechts.
• Ihr Mod hat einen neueren Toast ausgelöst: Im klassischen Renderer kann ein neuerer Toast Ihres Mods einen angezeigten oder noch wartenden Toast ersetzen. Das Debug-Log enthält eine weitere Zeile für den älteren Toast, die mit gave way, cut short endet, wenn er angezeigt wurde, oder mit gave way, unseen, wenn er nie erschienen ist. Um beide Meldungen anzuzeigen, fassen Sie sie in einem Toast zusammen.
• Die Zeit des Toasts ist abgelaufen, bevor er gezeichnet wurde: Im Vollbild-Rendering zeichnet Claude Code höchstens drei Toasts gleichzeitig, sodass die Zeit eines Toasts ablaufen kann, bevor er gezeichnet wird. Das Debug-Log enthält eine weitere Zeile für diesen Toast, die mit left the stack, never drawn endet. Wenn Ihr Mod mehrere gleichzeitig auslöst, fassen Sie die Meldungen in einem Toast zusammen.

Vor v2.1.290 verwarf Claude Code einen Toast, der innerhalb von zwei Sekunden nach dem letzten für Ihren Mod angezeigten Toast ausgelöst wurde, und die Debug-Log-Zeile für den verworfenen Toast lautete within 2000ms of the last; dropped.

Das Band zeigt plugin panel hidden

Das Band ist eingeklappt. Es wird eingeklappt, wenn Sie Ctrl+X und dann Ctrl+A drücken oder die Tasten, die Sie stattdessen belegt haben, und im Vollbild-Rendering, wenn Sie auf das [-] in seiner ersten Zeile klicken. Es bleibt eingeklappt, bis Sie es ausklappen oder Claude Code neu starten, und in dieser Zeit drückt keine Hotkey- oder action-Belegung eine Schaltfläche darin.

Um das Band auszuklappen, drücken Sie die Tasten, die die Zeile nennt, standardmäßig Ctrl+X und dann Ctrl+A, oder klicken Sie im Vollbild-Rendering auf die Zeile.

Hotkeys bewirken nichts

Ihr Bereich oder Band hat keinen Tastaturfokus, Ihre Schaltfläche befindet sich in einem eingeklappten Band, oder die Zeichnung befindet sich in der VS Code-Erweiterung, in der Schaltflächen keine Hotkeys haben. Gehen Sie je nach Fall so vor:

• Kein Tastaturfokus: Drücken Sie Ctrl+X und dann Tab oder klicken Sie im Vollbild-Rendering auf den Bereich oder das Band. Damit der Bereich beim Öffnen den Fokus erhält, öffnen Sie ihn mit focus: true über einen Befehl.
• Die Schaltfläche befindet sich in einem eingeklappten Band: Das Band zeigt eine abgeblendete Zeile, die mit ▸ plugin panel hidden beginnt. Drücken Sie die Tasten, die die Zeile nennt, standardmäßig Ctrl+X und dann Ctrl+A, um es auszuklappen.
• In der VS Code-Erweiterung: Klicken Sie auf die Schaltfläche oder drücken Sie Enter darauf, sobald sie den Fokus hat

Eine Zeichnung funktioniert im Terminal, aber nicht in der Desktop-App oder in VS Code

Entweder zeichnet diese App die Stelle oder das Element nicht, oder es handelt sich um eine Sitzung, in der die VS Code-Erweiterung nichts für Mods zeichnet. Die anderen Hooks des Mods werden weiterhin ausgeführt. Prüfen Sie diese Ursachen:

• Die Stelle oder das Element wird in dieser App nicht gezeichnet: Suchen Sie Ihre Stelle in der Tabelle der Render-Stellen und Ihre Elemente in der Tabelle der Elemente. Für ein Element, das der App fehlt, prüfen Sie e.surface im Hook und geben Sie einen Baum zurück, den die App zeichnen kann.
• Die VS Code-Erweiterung ist älter als 2.1.299: Das Chat-Panel zeichnet für Mods ab Erweiterungsversion 2.1.299. Prüfen Sie die Version in der Erweiterungsansicht von VS Code und aktualisieren Sie die Erweiterung dort.
• Die Erweiterung ist älter als 2.1.304 und die Sitzung ruft keine Feature-Flags ab: Aktualisieren Sie die Erweiterung oder führen Sie stattdessen claude im integrierten Terminal von VS Code aus. Sitzungen auf Amazon Bedrock, der Agent Platform von Google Cloud oder Microsoft Foundry überspringen den Abruf. Für die anderen, die ihn überspringen, etwa eine Sitzung über ein Claude Apps Gateway, siehe Funktionen, die den Abruf von Feature-Flags benötigen.

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.

Ein Schlüssel, den Ihr settings.read-Hook zurückgibt, wird nicht wirksam

Wenn Sie beim eigenen Lesevorgang von Claude Code Berechtigungsregeln oder env zurückgeben, werden die Regeln bei Tool-Aufrufen nicht geprüft, und die env-Einträge werden nicht zu Umgebungsvariablen. Verwenden Sie für beides eine Einstellungsdatei oder für env $.env.set.

Prüfen Sie bei einem anderen Schlüssel, welche Mods settings.read erhalten und ab welcher Version, durchsuchen Sie dann das Debug-Log nach settings.read und suchen Sie nach einer dieser Zeilen:

Wenn keine Zeile den Schlüssel erklärt, prüfen Sie die Mods, die vor Ihrem ausgeführt werden, auf einen settings.read-Hook, der den Schlüssel ändert. Schalten Sie diesen Mod aus, oder bitten Sie den Administrator Ihrer Organisation darum. Wenn kein Hook dies tut, legen Sie den Schlüssel in einer Einstellungsdatei fest.

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

Diese Zeile im Debug-Log bedeutet, dass Claude Code den Wert abgelehnt hat, den ein settings.read-Hook für den genannten Schlüssel zurückgegeben hat, und zwar nur für diesen Schlüssel:

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

Der für den genannten Schlüssel zurückgegebene Wert passte nicht zum Schema dieses Schlüssels, zum Beispiel hinsichtlich Typ oder Wertebereich.

• Ihr Wert passt nicht zum Schema des Schlüssels: Geben Sie einen Wert zurück, den der Eintrag des Schlüssels in der Einstellungsreferenz zulässt.
• Ihr Wert passt: Der nicht passende Wert stammt aus dem settings.read-Hook eines anderen Mods. Um diesen Mod zu finden, folgen Sie den Schritten, um Mods nacheinander auszuschalten. Durchsuchen Sie jedes neue Log nach dieser Zeile statt nach refused to the engine.

Solange der Wert nicht passt, behält der Schlüssel den Wert, der aus den Einstellungsquellen zusammengeführt wurde, bevor ein Hook geantwortet hat. Die Zeile nennt ihn den eigenen Wert der Einstellungen.

settings.read: refused to the engine

Sie sehen diese Zeile im Debug-Log, wenn der eigene Lesevorgang von Claude Code abgelehnt wird, und Claude Code verwirft den Wert jedes Hooks. Wenn ein settings.read-Hook diesen Lesevorgang mit { deny: reason } ablehnt, enthält die Zeile die Begründung dieses Hooks:

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

Durchsuchen Sie Ihren Code nach der Begründung in den Klammern:

• Ihr Code enthält ihn: Ihr Hook hat den Lesevorgang abgelehnt. Sorgen Sie dafür, dass er { value } zurückgibt, wenn next.origin den eigenen Lesevorgang von Claude Code anzeigt.
• Ihr Code enthält sie nicht: Schalten Sie Ihre anderen Mods nacheinander aus. Wenn Ihre Organisation einen Mod bereitgestellt hat, bitten Sie deren Administrator, ihn auszuschalten. Nach jedem Mod:
  1. Starten Sie die Sitzung aus Ihrer Shell mit claude --debug-file ./settings-read-2.log, gefolgt von den Flags, mit denen sie gestartet wurde. Verwenden Sie jedes Mal einen neuen Pfad.
  2. Durchsuchen Sie diese Datei nach refused to the engine. Wenn die Zeile vorhanden ist, schalten Sie den nächsten Mod aus. Wenn nicht, hat der zuletzt ausgeschaltete Mod den Lesevorgang abgelehnt; lassen Sie ihn also ausgeschaltet.

Wenn die Zeile bleibt und kein anderer Mod mehr übrig ist, legen Sie die Schlüssel, die Ihr Hook zurückgibt, in einer Einstellungsdatei fest. Deren Werte gelten, während der Lesevorgang abgelehnt wird.

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

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, bis Claude Code die Plugins das nächste Mal neu lädt, etwa wenn Sie /reload-plugins ausführen.

Nächste Schritte

• Einen Mod testen: Probleme erkennen, bevor sie eine Sitzung erreichen
• Fehlerbehebung bei Plugins: Probleme beim Installieren und Laden eines Plugins, die nicht spezifisch für Mods sind