Troubleshoot a mod
Cari tahu mengapa Claude Code mod tidak melakukan apa pun: cocokkan gejala atau pesan dengan penyebabnya, cari pesan penolakan, dan baca log debug.
Ketika modul mod atau salah satu hooks-nya gagal, Claude Code melewatinya dan sesi berlanjut, jadi mod yang rusak dapat terlihat seperti mod yang tidak melakukan apa pun. Mulai dengan memeriksa apa yang Claude Code baca dari mod Anda dan di mana ia melaporkan masalah, kemudian temukan gejala atau pesan yang Anda miliki.
Cari tahu mengapa mod tidak melakukan apa pun
Ketika mod tidak melakukan apa pun, dua pemeriksaan menemukan alasannya: apa yang Claude Code baca dari file mod, dan baris yang ditulis ketika melewati sesuatu. Untuk yang pertama, di shell Anda jalankan claude plugin validate dengan direktori mod, seperti claude plugin validate ./first-mod. Ini menangkap event yang salah eja, manifest yang buruk, dan modul yang tidak dapat dibaca Claude Code, tanpa memulai sesi.
Ketika modul tidak dimuat, hook dilewati, atau mod lain menolak milik Anda, Claude Code menulis satu baris yang menyebutkan mod Anda. Di mana Anda membaca baris itu tergantung pada sesi:
- Sesi yang hot-reload direktori plugin: baris redup dalam transkrip. Itu adalah sesi interaktif yang Anda mulai dengan
--plugin-dir, atau sesi di mana Anda mengaktifkan hot reloading untuk mod yang ditulis Claude. - Sesi interaktif lainnya, seperti sesi yang menjalankan mod yang Anda instal dari marketplace: debug log saja. Untuk mendapatkannya, mulai sesi dengan
claude --debug. - Jalankan
claude -pdengan--plugin-dir: stderr, dalam format output teks default. Penolakan oleh mod lain hanya masuk ke debug log.
Periksa apakah mod dapat dimuat
Untuk memeriksa apakah setup Anda memungkinkan mod dimuat sama sekali, tanpa menginstal satu, jalankan claude plugin test di shell Anda, dari direktori yang tidak menyimpan mod. Anda tidak memerlukan sesi. Pesan yang dicetak memberitahu Anda statusnya:
| Pesan mencakup | Artinya |
|---|---|
no hooks module to load |
Mod dapat dimuat. Perintah tidak menemukan mod untuk diuji di direktori ini. |
hooks modules are turned off here |
Pengaturan menjaga mod Anda keluar: disableAllHooks di pengaturan Anda sendiri, atau kebijakan organisasi Anda |
hooks modules are turned off in this process |
Anthropic telah mematikan mod yang diinstal dari jarak jauh. Tidak ada pengaturan di mesin Anda yang menghidupkannya kembali. |
Organisasi juga dapat mengatur allowManagedModsOnly untuk memungkinkan hanya mod miliknya sendiri, yang tidak dilaporkan perintah ini. Dalam hal itu mod yang Anda instal tidak dimuat, dan pesan menjelaskan mengapa.
Mod tidak dimuat
Tidak ada yang ditambahkan mod: tidak ada perintah, tidak ada gambar, dan tidak ada perubahan perilaku.
Versi Anda lebih lama dari 2.1.287
claude --version mencetak versi lebih lama dari 2.1.287. Versi Anda mendahului mod yang diaktifkan secara default.
Baris `mods active` tidak menyebutkan mod
Tidak ada yang ditambahkan mod, dan baris mods active di /plugin tidak menyebutkannya. Modul hooks tidak dimuat. Ketika Claude Code menolaknya, debug log memiliki baris yang dimulai dengan hooks module, nama mod, dan not loaded:, seperti hooks module first-mod@inline not loaded: disableAllHooks in managed settings untuk mod yang dimuat dengan --plugin-dir.
Baca alasan setelah titik dua. Bagian refusal messages mencantumkan masing-masing. Jika log tidak memiliki baris seperti itu, kerjakan entri lain dalam grup ini.
Jalankan `claude -p` mencetak `hooks module not loaded`
Baris dimulai dengan nama mod dan masuk ke stderr. Modul hooks ditolak. Jalankan non-interaktif tidak memiliki transkrip, jadi pesan masuk ke stderr.
Baca alasan setelah titik dua. Bagian refusal messages mencantumkan masing-masing.
Refusal messages
Masing-masing mengikuti hooks module, nama mod, dan not loaded: di debug log.
| Pesan dimulai dengan | Artinya |
|---|---|
hooks modules are turned off for installed plugins in this process |
Anthropic telah mematikan mod yang diinstal dari jarak jauh. Tidak ada pengaturan di mesin Anda yang menghidupkannya kembali. |
disableAllHooks in managed settings |
Organisasi Anda mematikan hooks dari plugin yang diinstal |
only managed plugins and built-in plugins run |
allowManagedHooksOnly diatur, atau disableAllHooks diatur dalam file pengaturan selain pengaturan terkelola |
installed plugins that are not managed load no hooks module in this mode (--bare) |
Anda memulai Claude Code dengan --bare |
another plugin of that name loads first |
Dua plugin berbagi nama. Yang terkelola, atau yang dimuat terlebih dahulu, digunakan. |
Pesan dari built-in guard
Pada mesin dengan pengaturan terkelola, atau untuk pengguna yang masuk dengan paket Team atau Enterprise, built-in guard dapat menolak mod atau salah satu jawabannya. Setiap pesan menyebutkan opsi yang ditetapkan administrator organisasi Anda untuk mengubah aturan.
| Pesan berisi | Artinya | Di mana muncul |
|---|---|---|
mods are limited to your organization's by policy (allowManagedModsOnly) |
Organisasi Anda hanya memungkinkan mod miliknya sendiri, jadi milik Anda tidak dimuat | Debug log, dan transkrip dalam sesi yang hot-reload direktori plugin |
tried to lift a deny rule in your settings |
Hook tool.check mod Anda menyetujui panggilan yang aturan deny menolak. Panggilan tetap ditolak. |
Transkrip dan debug log, sekali untuk setiap mod dalam sesi. Dalam jalankan claude -p, hanya debug log. |
the deny rules in your settings could not be checked for this call, so it is refused |
Guard gagal saat memeriksa panggilan yang disetujui mod, jadi menolak panggilan | Alasan Claude membaca untuk panggilan yang ditolak |
`validate` lulus dan tidak mencantumkan baris `hooks`
hooks/hooks.json tidak memiliki kunci modules, atau kunci salah eja.
Tambahkan "modules": ["./register.js"].
`hooks module did not load`
Baris dimulai dengan nama mod, kemudian hooks module did not load: dan alasan, yang memberikan file dan baris ketika masalah ada di kode Anda. Claude Code tidak dapat memuat modul, misalnya karena kode tingkat atasnya dilempar.
Perbaiki kesalahan yang dinamai alasan.
`options do not fit plugin.json userConfig`
Baris dimulai dengan nama mod, kemudian hooks module did not load: options do not fit plugin.json userConfig: dan alasan. Opsi tidak sesuai dengan bidang userConfig-nya, seperti angka di atas max bidang, atau bidang yang diperlukan tidak memiliki nilai.
Atur atau ubah nilainya. Akhir baris menyebutkan entri pluginConfigs-nya di settings.json.
Tidak ada mod yang dimuat di direktori yang Anda buka untuk pertama kalinya
Anda belum menjawab prompt kepercayaan untuk direktori.
Mulai sesi interaktif di direktori itu dengan claude, dan terima prompt kepercayaan yang dibukanya.
Tidak ada plugin yang diinstal dimuat sama sekali
Anda memulai Claude Code dengan --safe-mode.
Mulai tanpa flag.
Hook dilewati atau mod dibongkar
Mod dimuat, dan kemudian Claude Code melewati salah satu hooks-nya atau membongkarnya.
`hook skipped`
Baris menyebutkan mod dan event, kemudian mengatakan hook skipped: dan alasan, seperti first-mod: tool.call hook skipped: threw Error: boom. Hook dilempar, berjalan melampaui batas waktu 10 detik-nya, atau mengembalikan hasil bentuk yang salah. Baris muncul sekali untuk setiap event dan jenis kegagalan sampai mod dimuat ulang.
Perbaiki kesalahannya. Debug log memiliki baris untuk setiap kejadian.
`it crashed the hooks worker`
Baris dimulai dengan nama mod, seperti first-mod was unloaded: it crashed the hooks worker. Plugin yang diinstal berbagi satu thread worker. Worker berhenti merespons atau mogok, dan Claude Code melacak itu ke mod ini dan membongkarnya. Hook yang memblokir thread, seperti loop yang tidak pernah menunggu, adalah satu penyebab.
Perbaiki hook.
`mods that run in the hooks worker are off for this session`
Baris berbunyi hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. Worker berhenti tiga kali dan Claude Code tidak dapat melacak pemberhentian ke satu mod, jadi membongkar setiap mod yang bukan built-in, termasuk mod yang diinstal organisasi Anda. Baris ini mencapai transkrip di setiap sesi interaktif.
Jalankan /reload-plugins untuk memuatnya lagi.
Panggilan tool ditolak
Mod dimuat dan hooks-nya berjalan, dan panggilan tool yang disentuhnya ditolak.
`a hook changed this call's input after the model wrote it`
Dalam mode auto, panggilan tool yang ditolak memberikan alasan ini. Hook mengubah input panggilan tool setelah server-side classifier meninjau, jadi tinjauan itu tidak mencakup apa yang akan berjalan. Hook dapat berupa tool.call mod atau turn.step hook, atau hook pengaturan PreToolUse. Pesan tidak mengatakan yang mana.
Pesan memberitahu Claude untuk mengeluarkan panggilan sekali lagi seperti yang dicatat. Jika itu juga ditolak, hook mengubah input setiap kali, jadi matikan mod atau hook, atau tinggalkan mode auto dan setujui panggilan sendiri.
Pesan tentang aturan deny di pengaturan Anda
tried to lift a deny rule in your settings dan the deny rules in your settings could not be checked for this call, so it is refused keduanya berasal dari built-in guard.
Carinya di Messages from the built-in guard.
Gambar tidak muncul atau merespons
Mod dimuat, dan pane, band, atau kontrol tidak berperilaku seperti yang Anda harapkan.
Pane atau band kosong atau menampilkan konten biasa Claude Code
Tree yang dikembalikan hook tidak divalidasi. Dengan --plugin-dir, transkrip mengatakan ui.render (Pane) refused: dengan alasan, seperti first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own. Debug log memiliki a hook returned a tree that does not validate dengan alasan yang sama.
Baca alasan di baris itu. Penyebab umum adalah prop yang tidak diambil elemen dan elemen yang tidak dimiliki aplikasi.
`$.ui.open` berjalan dan tidak ada pane yang muncul
Panggilan tidak berasal dari sesuatu yang dilakukan pengguna, dan terminal lebih sempit dari 144 kolom.
Buka pane dari perintah atau tombol, atau periksa hasil isPlaced panggilan. Lihat Open a pane at the right time.
Hotkey tidak melakukan apa pun
Pane Anda tidak memiliki fokus keyboard.
Tekan Ctrl+X kemudian Tab, atau klik pane. Buka dengan focus: true dari perintah.
Gambar bekerja di terminal dan bukan di Desktop app
Situs atau elemen tidak tersedia di sana.
Periksa tabel render sites dan elements.
Edit atau nilai hilang
Mod berjalan, dan perubahan yang Anda buat atau nilai yang disimpannya tidak ada.
Edit Anda tidak berlaku
Anda mengedit plugin yang Anda instal. Claude Code menjalankan salinan cache untuk versi yang diinstal.
Kembangkan dengan --plugin-dir menunjuk ke salinan kerja Anda, seperti claude --plugin-dir ./first-mod, yang dimuat ulang saat Anda menyimpan.
Nilai direset saat modul dimuat ulang
Variabel tingkat modul diinisialisasi ulang pada setiap reload.
Simpan nilai di $.state atau $.store.
Nilai direset setelah `/clear`, `/resume`, atau `/branch`
Nilai direset, atau nilai yang disimpan diganti dengan default-nya. Masing-masing perintah itu mereset $.state ke default-nya, dan session.start tidak dipecat lagi.
Muat nilai yang disimpan lagi dalam hook classic.SessionStart.
Baca debug log
Debug log memiliki baris untuk setiap modul Claude Code dimuat atau menolak, setiap hook yang gagal, dan setiap hasil yang ditolak, jadi di situlah untuk mencari ketika transkrip menunjukkan tidak ada. Untuk menulis satu, di shell Anda mulai Claude Code dengan --debug, atau dengan --debug-file <path> untuk memilih di mana itu pergi:
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
Di terminal lain, ikuti file dan filter untuk nama mod Anda:
tail -f ./mod-debug.log | grep first-mod
Mod yang dimuat memiliki baris yang menyebutkannya dan mencantumkan event yang diaitkan. Mod yang dimuat dengan --plugin-dir muncul di bawah namanya diikuti oleh @inline:
hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render
Gambar yang tidak divalidasi dihitung sebagai hasil yang ditolak dan mendapat baris juga. Untuk menulis baris Anda sendiri di log, panggil $.ui.log dengan argumen kedua, seperti $.ui.log('message', { to: 'debug' }). Tanpa argumen kedua, $.ui.log menambahkan baris redup ke transkrip.
Saat Anda mengedit mod yang dimuat dengan --plugin-dir, transkrip menampilkan baris untuk setiap reload yang menyebutkan mod dan mencantumkan hooks-nya. Jika penyimpanan memecah modul, baris mengatakan reload failed, the previous version stays loaded: dengan alasan, dan versi terakhir yang berfungsi terus berjalan.
Langkah berikutnya
- Test a mod: tangkap masalah sebelum mencapai sesi
- Troubleshoot plugins: masalah dengan menginstal dan memuat plugin yang tidak spesifik untuk mod