mod のトラブルシューティング
Claude Code mod が何もしない理由を調べます。症状またはメッセージを原因と照合し、拒否メッセージを確認し、デバッグログを読みます。
mod のモジュールまたはそのいずれかのフックが失敗すると、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 を保持していないディレクトリから実行します。セッションは不要です。出力されるメッセージは状態を示します。
| メッセージに含まれる内容 | 意味 |
|---|---|
no hooks module to load |
mod は読み込めます。コマンドはこのディレクトリでテストする mod を見つかりませんでした。 |
hooks modules are turned off here |
設定が mod をブロックしています。ユーザー自身の設定の disableAllHooks、または組織のポリシー |
hooks modules are turned off in this process: the rollout switch served off |
Anthropic がインストール済み mod をリモートで無効にしました。 |
hooks modules are turned off in this process: the rollout switch was saved off by an earlier session |
コマンドは以前のセッションが保存した値を使用しました。この値は古い可能性があります。claude を一度起動して値を更新してから、コマンドを再度実行してください。 |
組織は 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: に続きます。
| メッセージの開始 | 意味 |
|---|---|
hooks modules are turned off for installed plugins in this process: the rollout switch served off |
Anthropic がインストール済み mod をリモートでオフにしました。 |
hooks modules are turned off for installed plugins in this process: the rollout switch was saved off by an earlier session |
セッションは以前のセッションが保存した値を使用しましたが、その値は古い可能性があります。Claude Code を再起動して値を更新してください。 |
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 のようになります。フックが例外をスローした、制限時間を超過した、または間違った形状の結果を返しました。行は 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.runhook がない、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 を修正します。
`its session.start ran again in a fresh copy`
行は mod の名前で始まり、$.prompt.submit、$.command.run、または $.agent.spawn の呼び出しを示します。例えば 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 が mod のモジュールを再度読み込み（例えばフックワーカーがクラッシュして置き換えられた後など）、新しいコピーの session.start フックが実行されました。行が示す呼び出しは、再度実行される代わりに最初の実行の結果で解決されたため、mod がプロンプトを送信したり、コマンドを実行したり、サブエージェントを開始したりすることが 2 回行われることはありません。フックの残りの部分は通常どおり実行されました。
修正する必要はありません。
v2.1.292 より前では、呼び出しが 2 回目も実行されたため、プロンプトの送信、コマンドの実行、またはサブエージェントの開始が 2 回行われていました。
`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 の通常のコンテンツを表示する
フックが返した ツリー が検証を通りませんでした。--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 と同じ理由があります。
その行の理由を読んでください。一般的な原因は、要素が受け付けない props と、アプリに存在しない要素です。
`ui.render` の行に `threw while drawn` と表示される
その行は 描画箇所 を示し、続いて threw while drawn: とエラーを示します。例えば first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own のようになります。Claude Code は、ui.render フックが返したツリーを描画する際、または フックが next に渡した props から描画箇所を描画する際に、そのエラーに遭遇しました。末尾の the engine drew its own は、その描画箇所に Claude Code の通常のコンテンツが表示されることを意味します。
エラーを読み、その原因となったフック内の値を修正してください。
v2.1.289 より前では、トランスクリプトの行でこのエラーが発生すると、Claude Code exited after an unrecoverable interface error でセッションが終了していました。
`the module failed without a message`
Client が、throw new Error() のようなメッセージのないエラーで失敗しました。その代わりに表示される行は my-mod: Client client/spinner.js: the module failed without a message のようになります。
Client のコード内で throw している箇所を見つけ、エラーにメッセージを付けてください。そうすると、その行にそのメッセージが表示されます。
v2.1.289 より前では、この行には理由として代わりに Error が表示されていました。
`$.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 が読み込むまたは拒否するすべてのモジュール、失敗するすべてのフック、拒否するすべての結果の行があります。トランスクリプトに何も表示されない場合は、ここを確認してください。書き込むには、シェルで 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 の名前を示し、そのフックをリストする各リロードの行を表示します。保存がモジュールを破損する場合、行は reload failed, the previous version stays loaded: と理由を示し、Claude Code が次にプラグインをリロードするまで（/reload-plugins を実行したときなど）、最後に機能したバージョンが実行され続けます。
次のステップ
- mod をテストする: セッションに到達する前に問題をキャッチします
- プラグインのトラブルシューティング: mod に固有ではないプラグインのインストールと読み込みに関する問題