mod のトラブルシューティング

Claude Code mod が何もしない理由を調べます。症状またはメッセージを原因と照合し、拒否メッセージを確認し、デバッグログを読みます。

mod のモジュールまたはそのいずれかの hooks が失敗すると、Claude Code はそれをスキップしてセッションが続行されるため、壊れた mod は何もしない mod のように見えることがあります。Claude Code が mod から読み込んだ内容と、問題を報告する場所を確認することから始めてください。その後、症状またはメッセージを見つけてください。

mod が何もしない理由を調べる

mod が何もしない場合は、Claude Code が mod のファイルから読み込む内容と、何かをスキップするときに書く行を確認します。前者については、シェルで claude plugin validate を mod のディレクトリで実行します。例えば claude plugin validate ./first-mod のようにします。セッションを開始せずに、スペルが間違ったイベント、不正なマニフェスト、Claude Code が読み込めないモジュールをキャッチします。

モジュールが読み込まれない場合、hooks がスキップされる場合、または別の mod があなたの mod を拒否する場合、Claude Code は mod の名前を付けた 1 行を書きます。その行を読む場所はセッションによって異なります。

• プラグインディレクトリをホットリロードするセッション: トランスクリプト内の薄い行。これは --plugin-dir で開始した対話型セッション、または Claude が書いた mod の ホットリロードを有効にした セッションです。
• マーケットプレイスからインストールした mod を実行するセッションなど、その他の対話型セッション: デバッグログ のみ。取得するには、セッションを claude --debug で開始します。
• --plugin-dir を使用した claude -p 実行: stderr、デフォルトのテキスト出力形式で。別の mod による拒否はデバッグログのみに移動します。

mod が読み込めるかどうかを確認する

mod が読み込めるかどうかを確認するには、mod をインストールせずに、シェルから claude plugin test を実行します。mod を保持していないディレクトリから実行します。セッションは不要です。出力されるメッセージは状態を示します。

組織は allowManagedModsOnly を設定して、独自の mod のみを許可することもできます。このコマンドはこれを報告しません。その場合、Claude Code はインストールした mod を拒否し、メッセージで理由が示されます。

mod が読み込まれない

mod が追加するものは何も表示されません。コマンド、描画、動作の変更はありません。

バージョンが古すぎる

使用するバージョンとバージョンの確認方法を参照してください。

`mods active` 行が mod の名前を示していない

mod が追加するものは何も表示されず、/plugin の mods active 行 にその名前がありません。hooks モジュールが読み込まれませんでした。Claude Code がそれを拒否したとき、デバッグログには hooks module、mod の名前、not loaded: で始まる行があります。例えば --plugin-dir で読み込まれた mod の場合 hooks module first-mod@inline not loaded: disableAllHooks in managed settings のようになります。

コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。ログにそのような行がない場合は、このグループの他のエントリを確認してください。

一部の設定は mod を停止しますが、そのプラグインの残りの部分は動作したままにします。mod をオンまたはオフにする でそれらの設定を挙げています。

`claude -p` 実行が `hooks module not loaded` を出力する

行は mod の名前で始まり、stderr に移動します。hooks モジュールが拒否されました。非対話型実行にはトランスクリプトがないため、メッセージは stderr に移動します。

コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。

拒否メッセージ

これらはそれぞれ、デバッグログの hooks module、mod の名前、not loaded: に続きます。

組み込みガードからのメッセージ

マネージド設定を持つマシン上、または Team または Enterprise プランでサインインしているユーザーの場合、組み込みガード は mod またはそのいずれかの回答を拒否できます。各メッセージは、組織の管理者が設定するオプションの名前を示します。

`validate` が成功し、`hooks` 行がリストされていない

hooks/hooks.json に modules キーがないか、キーのスペルが間違っています。

"modules": ["./register.js"] を追加します。

`hooks module did not load`

行は mod の名前で始まり、hooks module did not load: と理由が続きます。問題がコード内にある場合、ファイルと行を示します。Claude Code はモジュールを読み込めませんでした。例えば、トップレベルコードが例外をスローしたためです。

理由が示すエラーを修正します。

`options do not fit plugin.json userConfig`

行は mod の名前で始まり、hooks module did not load: options do not fit plugin.json userConfig: と理由が続きます。オプションが userConfig フィールドに対する検証に失敗しています。例えば、フィールドの max を超える数値である場合や、必須フィールドに値がない場合です。

値を設定または変更します。行の末尾は settings.json の pluginConfigs エントリの名前を示します。

初めて開いたディレクトリで mod が読み込まれない

ディレクトリの信頼プロンプトに答えていません。

claude でそのディレクトリで対話型セッションを開始し、開かれる信頼プロンプトを受け入れます。

インストール済みプラグインが読み込まれない

Claude Code を --safe-mode で開始しました。

フラグなしで開始します。

hooks がスキップされるか mod がアンロードされる

mod が読み込まれ、その後 Claude Code がそのいずれかの hooks をスキップするか、アンロードしました。

`hook skipped`

行は mod とイベントの名前を示し、hook skipped: と理由を示します。例えば first-mod: tool.call hook skipped: threw Error: boom のようになります。フックが例外をスローした、制限時間を超過した、または間違った形状の結果を返しました。行は mod がリロードされるまで、イベントと失敗の種類ごとに 1 回表示されます。

エラーを修正します。デバッグログには発生するたびに行があります。

`no command.run hook answered it`

mod が追加したコマンドを実行すると、返信は mod とコマンドの名前を示します。例えば first-mod registered /tally but no command.run hook answered it のようになり、hook を追加するよう指示します。Claude Code はコマンドがチェーンの終わりに到達して答えがない場合にその返信を出力します。これは 2 つのケースで発生します。

• hook がコマンドに答えなかった: モジュールに command.run hook がない、hook の filter が別のコマンドを指定している、または hook が next(e) を返した
• Claude Code が hook をスキップした: hook skipped が理由を列挙します。$.ui.open に focus: false を渡すことは、そこに到達する 1 つの方法です。

モジュールが既に返信が説明する hook を持っている場合、command.run という名前の hook skipped 行を探してください。これが理由を示します。コマンドを実行する test は同じ理由で失敗します。

`it crashed the hooks worker`

行は mod の名前で始まります。例えば first-mod was unloaded: it crashed the hooks worker のようになります。インストール済み mod は 1 つのワーカースレッドを共有します。ワーカーが応答を停止するか、クラッシュし、Claude Code がそれをこの mod に追跡して、アンロードしました。スレッドをブロックする hooks。例えば、await しないループが 1 つの原因です。

hooks を修正します。

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

行は hooks: mods that run in the hooks worker are off for this session: it crashed 3 times と読みます。ワーカーが 3 回停止し、Claude Code が停止を 1 つの mod に追跡できなかったため、組み込みでない mod をすべてアンロードしました。組織がインストールする mod を含みます。この行はすべての対話型セッションのトランスクリプトに到達します。

/reload-plugins を実行してそれらを再度読み込みます。

ツール呼び出しが拒否される

mod が読み込まれ、その hooks が実行され、それが触れたツール呼び出しが拒否されます。

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

自動モードでは、拒否されたツール呼び出しはこの理由を示します。hooks が サーバー側分類器 がレビューした後、ツール呼び出しの入力を変更したため、そのレビューは実行される内容をカバーしません。hooks は mod の tool.call または turn.step hooks、または PreToolUse 設定 hooks である可能性があります。メッセージはどれかを示しません。

メッセージは Claude に記録されたとおりに呼び出しを再度発行するよう指示します。それも拒否された場合、hooks は毎回入力を変更するため、mod または hooks をオフにするか、自動モードを離れて呼び出しを自分で承認します。

設定の拒否ルールに関するメッセージ

tried to lift a deny rule in your settings と the deny rules in your settings could not be checked for this call, so it is refused は両方とも組み込みガードから来ます。

組み込みガードからのメッセージ で確認してください。

描画が表示されないか応答しない

mod が読み込まれ、そのペイン、バンド、またはコントロールが期待どおりに動作しません。

ペインまたはバンドが空であるか、Claude Code の通常のコンテンツを表示する

ツリー が hooks から返されたものが検証されませんでした。--plugin-dir を使用すると、トランスクリプトは ui.render (Pane) refused: と理由を示します。例えば first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own のようになります。デバッグログには a hook returned a tree that does not validate と同じ理由があります。

その行の理由を読んでください。一般的な原因は、要素が取らないプロップと、アプリが持たない要素です。

`$.ui.open` が実行され、ペインが表示されない

呼び出しはユーザーが行ったものから来ておらず、ターミナルは そのペインに必要な幅 より狭いです。

コマンドまたはボタンからペインを開くか、呼び出しの isPlaced 結果を確認します。適切なタイミングでペインを開く を参照してください。

ホットキーが何もしない

ペインにキーボードフォーカスがありません。

Ctrl+X を押してから Tab を押すか、ペインをクリックします。focus: true を使用してコマンドから開きます。

描画がターミナルで機能し、Desktop アプリでは機能しない

サイトまたは要素はそこで利用できません。

レンダリングサイト と 要素 テーブルを確認してください。

編集または値が失われる

mod が実行され、行った変更または保持していた値がありません。

編集が有効にならない

インストールした plugin を編集しています。Claude Code はインストール済みバージョンのキャッシュされたコピーを実行します。

claude --plugin-dir ./first-mod のように、作業コピーを指す --plugin-dir で開発します。保存時にリロードされます。

モジュールがリロードされるときに値がリセットされる

モジュールレベルの変数は各リロード時に再初期化されます。

値を $.state または $.store に保持します。

`/clear`、`/resume`、または `/branch` の後に値がリセットされる

値がリセットされるか、保存された値がデフォルトに置き換わります。これらのコマンドはそれぞれ $.state をデフォルトにリセットし、session.start は再度発火しません。

classic.SessionStart hooks で保存された値を再度読み込みます。

デバッグログを読む

デバッグログには、Claude Code が読み込むまたは拒否するすべてのモジュール、失敗するすべての hooks、拒否するすべての結果の行があります。トランスクリプトに何も表示されない場合は、ここを確認してください。書き込むには、シェルで Claude Code を --debug で開始するか、--debug-file <path> で場所を選択します。

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

別のターミナルで、ファイルをフォローして mod の名前でフィルタリングします。

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

読み込まれた mod には、その名前を示し、処理するイベントをリストする行があります。--plugin-dir で読み込まれた mod は、その名前の後に @inline が続く形で表示されます。

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

検証されなかった描画は拒否された結果としてカウントされ、行も取得します。ログに独自の行を書き込むには、$.ui.log を 2 番目の引数で呼び出します。例えば $.ui.log('message', { to: 'debug' }) のようにします。2 番目の引数がない場合、$.ui.log はトランスクリプトに薄い行を追加します。

--plugin-dir で読み込まれた mod を編集している間、トランスクリプトは mod の名前を示し、その hooks をリストする各リロードの行を表示します。保存がモジュールを破損する場合、行は reload failed, the previous version stays loaded: と理由を示し、最後に機能したバージョンが実行され続けます。

次のステップ

• mod をテストする: セッションに到達する前に問題をキャッチします
• プラグインのトラブルシューティング: mod に固有ではないプラグインのインストールと読み込みに関する問題