Skip to main content
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 -p dengan --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: 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. Perbarui Claude Code.

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

​
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:
Di terminal lain, ikuti file dan filter untuk nama mod Anda:
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:
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