mod のトラブルシューティング
Claude Code mod が何もしない理由を調べます。症状またはメッセージを原因と照合し、拒否メッセージを確認し、デバッグログを読みます。
mod のモジュールまたはそのいずれかの hooks が失敗すると、Claude Code はそれをスキップしてセッションが続行されるため、壊れた mod は何もしない mod のように見えることがあります。Claude Code が mod から読み込んだ内容と、問題を報告する場所を確認することから始めてください。その後、症状またはメッセージを見つけてください。
mod が何もしない理由を調べる
mod が何もしない場合、2 つのチェックで理由が分かります。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 を保持していないディレクトリから実行します。セッションは不要です。出力されるメッセージは状態を示します。
| メッセージに含まれる内容 | 意味 |
|---|---|
no hooks module to load |
mod は読み込めます。コマンドはこのディレクトリでテストする mod を見つかりませんでした。 |
hooks modules are turned off here |
設定が mod を除外しています。あなた自身の設定の disableAllHooks、または組織のポリシー |
hooks modules are turned off in this process |
Anthropic がインストール済み mod をリモートで無効にしました。マシン上の設定でそれらをオンに戻すことはできません。 |
組織は allowManagedModsOnly を設定して、独自の mod のみを許可することもできます。このコマンドはこれを報告しません。その場合、インストールした mod は読み込まれず、メッセージが理由を示します。
mod が読み込まれない
mod が追加するものは何も表示されません。コマンド、描画、動作の変更はありません。
バージョンが 2.1.287 より古い
claude --version は 2.1.287 より古いバージョンを出力します。バージョンは 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 のようになります。
コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。ログにそのような行がない場合は、このグループの他のエントリを確認してください。
`claude -p` 実行が `hooks module not loaded` を出力する
行は mod の名前で始まり、stderr に移動します。hooks モジュールが拒否されました。非対話型実行にはトランスクリプトがないため、メッセージは stderr に移動します。
コロンの後の理由を読んでください。拒否メッセージ セクションに各メッセージが記載されています。
拒否メッセージ
これらはそれぞれ、デバッグログの hooks module、mod の名前、not loaded: に続きます。
| メッセージの開始 | 意味 |
|---|---|
hooks modules are turned off for installed plugins in this process |
Anthropic がインストール済み mod をリモートで無効にしました。マシン上の設定でそれらをオンに戻すことはできません。 |
disableAllHooks in managed settings |
組織がインストール済みプラグインからの hooks をオフにしました |
only managed plugins and built-in plugins run |
allowManagedHooksOnly が設定されているか、マネージド設定以外の設定ファイルで disableAllHooks が設定されています |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Claude Code を --bare で開始しました |
another plugin of that name loads first |
2 つのプラグインが同じ名前を共有しています。マネージド版、または最初に読み込まれたものが使用されます。 |
組み込みガードからのメッセージ
マネージド設定を持つマシン上、または Team または Enterprise プランでサインインしているユーザーの場合、組み込みガード は mod またはそのいずれかの回答を拒否できます。各メッセージは、組織の管理者が設定するオプションの名前を示します。
| メッセージに含まれる内容 | 意味 | 表示される場所 |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
組織は 独自の mod のみを許可しているため、あなたの mod は読み込まれませんでした | デバッグログ、および プラグインディレクトリをホットリロードするセッション のトランスクリプト |
tried to lift a deny rule in your settings |
mod の tool.check hook が deny ルールが拒否する呼び出しを承認しました。呼び出しは拒否されたままです。 |
トランスクリプトとデバッグログ。セッション内の各 mod に対して 1 回。claude -p 実行では、デバッグログのみ。 |
the deny rules in your settings could not be checked for this call, so it is refused |
ガードが mod が承認した呼び出しをチェック中に失敗したため、呼び出しを拒否しました | Claude が拒否された呼び出しについて読む理由 |
`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 のようになります。hooks が例外をスロー、10 秒のタイムリミット を超過、または間違った形状の結果を返しました。行は mod がリロードされるまで、イベントと失敗の種類ごとに 1 回表示されます。
エラーを修正します。デバッグログには発生するたびに行があります。
`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` が実行され、ペインが表示されない
呼び出しはユーザーが行ったものから来ておらず、ターミナルは 144 列より狭いです。
コマンドまたはボタンからペインを開くか、呼び出しの 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 には、その名前を示し、hooks するイベントをリストする行があります。--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 に固有ではないプラグインのインストールと読み込みに関する問題