Memecahkan masalah mod

Cari tahu mengapa mod Claude Code tidak melakukan apa pun: cocokkan gejala atau pesan dengan penyebabnya, cari pesan penolakan, dan baca log debug.

Ketika modul mod atau salah satu hook-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, periksa apa yang Claude Code baca dari file mod, dan baris yang ditulisnya 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 Claude Code menolak mod yang Anda instal, 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 terlalu lama

Lihat versi mana yang digunakan dan cara memeriksa versi Anda.

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.

Beberapa pengaturan menghentikan mod dan membiarkan bagian lain dari plugin-nya tetap berfungsi. Aktifkan atau matikan mod menyebutkan pengaturan tersebut.

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 dalam sesi yang kredensialnya berupa /login Team atau Enterprise, penjaga bawaan 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.

Jika alasan diakhiri dengan ; the version loaded before is unloaded, tidak ada versi mod yang sedang berjalan saat ini. Setelah Anda memperbaiki kesalahan, jalankan /reload-plugins dalam sesi untuk memuat mod lagi. Jika Anda menginstal mod dan tidak menulisnya, minta penulisnya untuk memperbaiki kesalahan tersebut.

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 gagal validasi terhadap 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.

code nested too deep to scan: more than 2000 scopes

Baris dimulai dengan nama mod, kemudian hooks module did not load:, file, dan code nested too deep to scan: more than 2000 scopes. File dalam modul hook tidak dapat menyarangkan scope, seperti fungsi, blok, dan loop, lebih dari 2.000 tingkat. claude plugin validate melaporkan alasan yang sama.

Tulis ulang kode agar scope-nya tidak bersarang terlalu dalam.

the engine ran out of stack linking the file and its imports

Kode dalam modul hook bersarang terlalu dalam, atau rantai import-nya terlalu panjang, sehingga Claude Code tidak dapat memuatnya. Baris dimulai dengan nama mod dan hooks module did not load:, kemudian memberikan nama file dan alasan ini.

Periksa file tersebut dan file yang dijangkau melalui import-nya untuk menemukan bagian yang paling dalam bersarang, lalu tulis ulang agar tidak bersarang terlalu dalam, atau perpendek rantai import. Jika Anda tidak menulis mod tersebut, minta penulisnya untuk memperbaikinya.

the parser stopped atau the engine ran out of stack loading the file

Kode dalam salah satu file modul hook bersarang begitu dalam sehingga Claude Code kehabisan stack saat membacanya. Baris dimulai dengan nama mod dan hooks module did not load:, kemudian memberikan nama file tersebut dan salah satu alasan berikut:

• code nested too deep to scan (the parser stopped: <message>)
• the engine ran out of stack loading the file (code nested too deep): <message>

Alasan tersebut tidak memberikan nomor baris dan tidak menyebutkan jenis kode apa yang bersarang, jadi periksa sendiri file tersebut untuk menemukan bagiannya yang paling dalam bersarang. Tulis ulang bagian itu agar tidak bersarang terlalu dalam. Jika Anda menginstal mod dan tidak menulisnya, minta penulisnya untuk melakukannya.

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.

Claude Code berhenti menanyakan untuk mengaktifkan hot reloading

Claude menulis mod dalam sesi interaktif, tidak ada yang dimuat, dan Claude Code tidak lagi menanyakan apakah akan mengaktifkan hot reloading. Jika pertanyaan berakhir tiga kali tanpa jawaban yang dipilih, hot reloading tetap mati. Misalnya, pertanyaan berakhir seperti itu ketika Anda mengatur askUserQuestionTimeout dan waktunya habis sebelum Anda menjawab. Pengaturan itu berlaku di sini karena Claude Code bertanya dalam dialog pertanyaan yang sama yang digunakan AskUserQuestion. Pertanyaan yang Anda tutup sendiri tidak dihitung dalam tiga kali tersebut.

Untuk menjalankan mod, salin direktorinya keluar dari folder mods, lalu di shell Anda mulai sesi baru dengan --plugin-dir, seperti claude --plugin-dir ~/mods/git-branch.

Hook dilewati atau mod dibongkar

Mod dimuat, dan kemudian Claude Code melewati salah satu hooknya atau membongkarnya.

hook skipped

Baris tersebut menyebutkan nama mod dan acara, kemudian mengatakan hook skipped: dan alasan, seperti first-mod: tool.call hook skipped: threw Error: boom. Hook melempar, melampaui batas waktunya, atau mengembalikan hasil dengan bentuk yang salah. Baris muncul sekali untuk setiap acara dan jenis kegagalan sampai mod dimuat ulang.

Perbaiki kesalahan. Debug log memiliki baris untuk setiap kejadian.

no command.run hook answered it

Anda menjalankan perintah yang ditambahkan mod Anda, dan balasan menyebutkan mod dan perintah, seperti first-mod registered /tally but no command.run hook answered it, kemudian memberi tahu Anda untuk menambahkan hook. Claude Code mencetak balasan itu ketika perintah mencapai akhir rantai tanpa jawaban, yang terjadi dalam dua kasus:

• Tidak ada hook yang menjawab perintah: modul tidak memiliki hook command.run, filter hook menyebutkan perintah yang berbeda, atau hook mengembalikan next(e)
• Claude Code melewati hook: hook skipped mencantumkan alasannya. Meneruskan focus: false ke $.ui.open adalah salah satu cara untuk sampai ke sana.

Jika modul sudah memiliki hook yang dijelaskan balasan, cari baris hook skipped yang menyebutkan command.run, yang memberikan alasannya. Test yang menjalankan perintah gagal dengan alasan yang sama.

it crashed the hooks worker

Baris dimulai dengan nama mod, seperti first-mod was unloaded: it crashed the hooks worker. Mod 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 salah satu penyebabnya.

Perbaiki hook.

its session.start ran again in a fresh copy

Baris dimulai dengan nama mod dan menyebutkan panggilan $.prompt.submit, $.command.run, atau $.agent.spawn, seperti 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 memuat modul mod tersebut lagi, misalnya setelah worker hooks mogok dan diganti, dan hook session.start dari salinan baru dijalankan. Panggilan yang disebutkan baris tersebut diselesaikan dengan hasil dari eksekusi pertamanya alih-alih dijalankan lagi, sehingga mod Anda tidak mengirimkan prompt, menjalankan perintah, atau memulai subagent dua kali. Sisa hook berjalan seperti biasa.

Tidak ada yang perlu diperbaiki.

Sebelum v2.1.292, panggilan tersebut dijalankan untuk kedua kalinya, sehingga prompt dikirimkan, perintah dijalankan, atau subagent dimulai dua kali.

This mod's change didn't load atau the earlier version is no longer running

Perubahan pada mod yang ditulis Claude dalam sesi ini tidak dapat dimuat. Baris transkrip dimulai dengan nama mod dan diakhiri dengan alasannya:

• This mod's change didn't load, so the earlier version is still running: <reason>.
• This mod didn't load, and the earlier version is no longer running: <reason>.

Claude tidak melihat baris ini, jadi tempelkan baris tersebut ke pesan Anda berikutnya saat Anda meminta Claude untuk memperbaikinya.

$.agent.register refused: the hooks module that made the call is no longer loaded

Baris dimulai dengan nama mod Anda, seperti first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed), dan agent tidak terdaftar. Mod Anda dimuat ulang atau dibongkar sebelum panggilan tersebut. Pemuatan ulang memuat salinan baru dari modul hook, dan panggilan ini berasal dari kode yang masih berjalan di salinan lama, seperti hook yang belum selesai mengembalikan hasil.

Jika hook tersebut tidak menangkap penolakan, hook akan gagal dan Claude Code melewatinya. Untuk mendaftarkan agent dari salinan yang tetap dimuat, lakukan panggilan tersebut di hook session.start Anda, yang dijalankan lagi di setiap salinan baru setelah pemuatan ulang.

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 bawaan, 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.

Toast muncul setelah giliran dihentikan

Stopped: type a message to continue; a mod cannot resume work after Stop

Toast ini berarti bahwa setelah Anda menghentikan giliran, misalnya dengan Esc, sebuah mod mencoba memulai pekerjaan dengan sendirinya dan Claude Code tidak mengizinkannya. Tidak ada yang perlu diperbaiki. Setelah pesan Anda berikutnya, mod dapat memulai pekerjaan lagi dan sebagian dari pekerjaan tersebut akan kembali dengan sendirinya. Jika apa yang Anda harapkan dari mod tersebut tidak kembali, mintalah lagi atau jalankan kembali perintah mod tersebut.

Jika Anda yang menulis mod tersebut, lihat Panggilan dan pekerjaan latar belakang setelah pengguna menginterupsi giliran.

Gambar tidak muncul atau merespons

Mod dimuat, dan pane, band, toast, atau kontrol tidak berperilaku seperti yang Anda harapkan.

Band mod lain ditampilkan dan band Anda tidak

Hanya ada satu band di atas prompt, dan setiap mod berbagi band tersebut. Mod yang berjalan sebelum mod Anda menggantikan band Anda ketika mod tersebut mengembalikan tree yang tidak berisi hasil next(e). Untuk menampilkan kedua band, ubah hook mod tersebut, atau minta pembuatnya untuk:

• Mempertahankan band setelahnya: letakkan hasil await next(e) di antara children dari sebuah Box di tree-nya, seperti pada tab Band di atas prompt dari Pilih tempat menggambar
• Menjaga tree tetap valid: jangan berikan prop width, height, minWidth, minHeight, position, top, left, right, bottom, display, atau overflow pada Box tersebut, atau pada Box mana pun yang mengelilinginya

Untuk menemukan mod tersebut, tulis debug log dan cari answered ui.render without next() di dalamnya. Baris seperti other-mod (user) answered ui.render without next() menyebutkan mod yang mengembalikan tree-nya tanpa memanggil next(e). Baris tersebut tidak menyebutkan titik render, sehingga mod yang hanya menggunakan pane juga dapat muncul. Mod yang memanggil next(e) lalu membuang hasilnya tidak menghasilkan baris apa pun, jadi periksa juga hook yang berjalan sebelum hook Anda.

Band sebuah mod juga tidak muncul ketika tree yang dikembalikan hook-nya sendiri tidak lolos validasi, sementara band mod lain tetap ada. Untuk mengetahui mod mana dan alasannya, tulis debug log dan cari ui.render hook skipped di dalamnya.

Pane atau band kosong atau menampilkan konten biasa Claude Code

Tree yang dikembalikan hook Anda tidak lolos validasi. Baris hook skipped di transkrip atau debug log menyebutkan mod Anda dan alasannya, seperti baris berikut untuk sebuah Box di pane:

first-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse)

Perbaiki hal yang disebutkan alasan tersebut. Jika alasannya terpotong, tulis debug log dan cari a hook returned a tree that does not validate di dalamnya untuk membaca sisanya.

Jika baris tersebut justru mengatakan refused: tepat setelah nama titik render, seperti ui.render (Pane) refused:, lihat Baris ui.render mengatakan refused.

Baris ui.render mengatakan refused

ui.render (<site>) refused:, atau ui.render (<site>): the chain settled on a tree that does not validate di debug log, berarti tree di titik tersebut melampaui batas ukuran. Kedua baris tersebut menyebutkan titik render lalu alasannya, dan alasan tersebut menyebutkan batasnya.

Ubah mod yang menggambar di titik tersebut agar hook ui.render mereka mengembalikan tree yang lebih kecil, atau minta pembuatnya untuk melakukannya. Jika baris transkrip diawali dengan hooks, lebih dari satu mod yang dimuat memiliki hook ui.render untuk titik tersebut, jadi periksa tree setiap mod tersebut. Untuk beberapa mod yang band-nya di atas prompt bersarang menjadi tree dengan kedalaman lebih dari 32 tingkat, barisnya berbunyi:

hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn

Sebelum v2.1.307, baris refused: untuk titik mana pun melaporkan tree apa pun yang tidak lolos validasi, dan untuk Pane dan AbovePrompt baris tersebut diakhiri dengan ; the engine drew its own. Pada rilis tersebut, perbaiki hal yang disebutkan alasan tersebut.

needs a key, is drawn twice, atau key each once

Sebuah elemen di tree yang dikembalikan hook ui.render Anda tidak memiliki key yang valid, atau dua elemen menggunakan key yang sama. Temukan pesan yang Anda dapatkan:

• <Input> needs a key atau <Select> needs a key: elemen tersebut tidak memiliki prop key, atau key-nya kosong atau bukan string, seperti key: 3. Berikan string yang tidak kosong sebagai key-nya.
• <Button> needs a key: berikan string yang tidak kosong sebagai key tombol tersebut
• is drawn twice; each takes its own key: dua elemen dari jenis yang disebutkan pesan tersebut memiliki key yang sama, seperti Input "size" is drawn twice; each takes its own key. Berikan key tersendiri untuk setiap elemen.
• key each once dari press dalam pengujian: gambar memiliki lebih dari satu tombol dengan key yang Anda teruskan. Tombol dengan label yang sama dan tanpa prop key menggunakan label tersebut sebagai key-nya. Berikan key tersendiri untuk setiap tombol.

Baris ui.render mengatakan threw while drawn

Baris tersebut menyebutkan titik render, lalu mengatakan threw while drawn: dan error-nya, seperti first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own. Claude Code mengalami error tersebut saat menggambar tree yang dikembalikan hook ui.render Anda, atau saat menggambar titik tersebut dari props yang diteruskan hook Anda ke next. Akhiran the engine drew its own berarti titik tersebut menampilkan konten biasa Claude Code.

Baca error-nya dan perbaiki nilai di hook Anda yang menyebabkannya.

Sebelum v2.1.289, error ini pada baris transkrip mengakhiri sesi dengan Claude Code exited after an unrecoverable interface error.

the module failed without a message

Sebuah Client gagal dengan error yang tidak memiliki pesan, seperti throw new Error(). Baris di tempatnya berbunyi seperti my-mod: Client client/spinner.js: the module failed without a message.

Temukan throw di kode Client Anda dan berikan pesan pada error tersebut. Baris tersebut kemudian menampilkan pesan itu.

Sebelum v2.1.289, baris tersebut menampilkan Error sebagai alasannya.

$.ui.open berjalan dan tidak ada pane yang muncul

Panggilan tidak berasal dari sesuatu yang dilakukan pengguna, dan terminal lebih sempit dari lebar yang dibutuhkan pane tersebut.

Buka pane dari perintah atau tombol, atau periksa hasil isPlaced panggilan. Lihat Open a pane at the right time.

Toast tidak muncul

Mod Anda memanggil $.ui.toast dalam sesi terminal interaktif dan Anda tidak melihat toast tersebut. Untuk memastikan bahwa panggilan tersebut berjalan, cari di debug log baris yang berisi nama mod Anda dan teks toast, seperti $.ui.toast (first-mod): build finished. Kemudian periksa penyebab seperti berikut:

• Baris untuk panggilan tersebut tidak ada: cari baris yang menjelaskan mengapa Claude Code menolak panggilan tersebut, seperti first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000.
• Sebuah pane sedang menahan toast: mod Anda atau mod lain meneruskan holdToasts saat membuka pane yang sedang ditampilkan. Tutup pane tersebut untuk mengakhiri penahanan. Jika pane tersebut milik Anda dan memang dimaksudkan untuk tetap terbuka, hapus holdToasts dari panggilan $.ui.open-nya dan buka pane tersebut lagi.
• Toast berada di bawah prompt: di renderer klasik, lihat di sebelah kanan di bawah prompt. Toast di sana berupa satu baris yang diawali dengan nama mod, bukan kotak di kanan atas.
• Mod Anda memunculkan toast yang lebih baru: di renderer klasik, toast yang lebih baru dari mod Anda dapat menggantikan toast yang sedang ditampilkan atau sedang menunggu untuk ditampilkan. Debug log memiliki baris lain untuk toast yang lebih lama, yang diakhiri dengan gave way, cut short jika toast tersebut sedang ditampilkan, atau gave way, unseen jika toast tersebut tidak pernah muncul. Untuk menampilkan kedua pesan, letakkan keduanya dalam satu toast.
• Waktu toast habis sebelum digambar: dalam rendering fullscreen, Claude Code menggambar paling banyak tiga toast sekaligus, sehingga waktu sebuah toast dapat habis sebelum toast tersebut digambar. Debug log memiliki baris lain untuk toast tersebut, yang diakhiri dengan left the stack, never drawn. Ketika mod Anda memunculkan beberapa toast sekaligus, letakkan pesan-pesannya dalam satu toast.

Sebelum v2.1.290, Claude Code membuang toast yang dimunculkan dalam dua detik sejak toast terakhir yang ditampilkannya untuk mod Anda, dan baris debug log untuk toast yang dibuang tersebut mengatakan within 2000ms of the last; dropped.

Band menampilkan plugin panel hidden

Band sedang diciutkan. Band diciutkan saat Anda menekan Ctrl+X lalu Ctrl+A, atau tombol yang Anda tetapkan sebagai gantinya, dan dalam rendering fullscreen saat Anda mengklik [-] di baris pertamanya. Band tetap diciutkan hingga Anda membentangkannya atau memulai Claude Code lagi, dan selama itu tidak ada hotkey atau binding action yang menekan tombol di dalamnya.

Untuk membentangkan band, tekan tombol yang disebutkan baris tersebut, Ctrl+X lalu Ctrl+A secara default, atau dalam rendering fullscreen klik baris tersebut.

Hotkey tidak melakukan apa pun

Pane atau band Anda tidak memiliki fokus keyboard, tombol Anda berada di band yang diciutkan, atau gambar berada di ekstensi VS Code, tempat tombol tidak memiliki hotkey. Lakukan yang sesuai:

• Tidak ada fokus keyboard: tekan Ctrl+X kemudian Tab atau, dalam rendering fullscreen, klik pane atau band. Agar pane mengambil fokus saat dibuka, buka pane tersebut dengan focus: true dari perintah.
• Tombol berada di band yang diciutkan: band menampilkan satu baris redup yang diawali dengan ▸ plugin panel hidden. Tekan tombol yang disebutkan baris tersebut, Ctrl+X lalu Ctrl+A secara default, untuk membentangkannya.
• Di ekstensi VS Code: klik tombol, atau tekan Enter pada tombol tersebut setelah tombol itu mendapat fokus

Gambar bekerja di terminal dan bukan di Desktop app atau VS Code

Aplikasi tersebut tidak menggambar titik render atau elemen tersebut, atau sesi tersebut adalah sesi di mana ekstensi VS Code tidak menggambar apa pun untuk mod. Hook lain dari mod tersebut tetap berjalan. Periksa penyebab berikut:

• Titik render atau elemen tidak digambar di aplikasi tersebut: cari titik render Anda di tabel titik render dan elemen Anda di tabel elemen. Untuk elemen yang tidak dimiliki aplikasi, periksa e.surface di hook dan kembalikan tree yang dapat digambar oleh aplikasi tersebut.
• Ekstensi VS Code lebih lama dari 2.1.299: panel chat menggambar untuk mod mulai dari versi ekstensi 2.1.299. Periksa versinya di tampilan Extensions VS Code dan perbarui ekstensi di sana.
• Ekstensi lebih lama dari 2.1.304 dan sesi tidak mengambil feature flag: perbarui ekstensi, atau jalankan claude di terminal terintegrasi VS Code sebagai gantinya. Sesi di Amazon Bedrock, Agent Platform milik Google Cloud, atau Microsoft Foundry melewati pengambilan tersebut. Untuk sesi lain yang melewatinya, seperti sesi Claude apps gateway, lihat Fitur yang memerlukan pengambilan feature flag.

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.

Kunci yang dikembalikan hook settings.read Anda tidak berlaku

Jika Anda mengembalikan aturan izin atau env pada pembacaan milik Claude Code sendiri, aturan tersebut tidak diperiksa pada panggilan tool dan entri env tidak menjadi environment variable. Gunakan file pengaturan untuk keduanya, atau $.env.set untuk env.

Untuk kunci lain, periksa mod mana yang mendapatkan settings.read dan sejak versi berapa, lalu cari settings.read di log debug dan temukan salah satu baris berikut:

Jika tidak ada baris yang menjelaskan kunci tersebut, periksa mod yang berjalan sebelum mod Anda untuk menemukan hook settings.read yang mengubah kunci tersebut. Matikan mod tersebut, atau minta admin organisasi Anda untuk melakukannya. Jika tidak ada hook yang mengubahnya, tetapkan kunci tersebut di file pengaturan.

the answer for <key> is no value the key can hold

Baris log debug ini berarti Claude Code menolak nilai yang dikembalikan sebuah hook settings.read untuk kunci yang disebutkan, dan hanya untuk kunci tersebut:

settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

Nilai yang dikembalikan untuk kunci yang disebutkan tidak sesuai dengan skema kunci tersebut, misalnya dari segi tipe atau rentang.

• Nilai Anda tidak sesuai dengan skema kunci tersebut: kembalikan nilai yang diizinkan oleh entri kunci tersebut di referensi pengaturan.
• Nilai Anda sesuai: nilai yang tidak sesuai berasal dari hook settings.read milik mod lain. Untuk menemukan mod tersebut, ikuti langkah-langkah untuk mematikan mod satu per satu. Cari baris ini di setiap log baru, alih-alih refused to the engine.

Selama nilai tersebut tidak sesuai, kunci tersebut mempertahankan nilai hasil penggabungan dari sumber pengaturan sebelum hook mana pun menjawab. Baris tersebut menyebutnya sebagai nilai milik pengaturan itu sendiri.

settings.read: refused to the engine

Anda melihat baris ini di log debug ketika pembacaan milik Claude Code sendiri ditolak, dan Claude Code membuang nilai dari setiap hook. Ketika sebuah hook settings.read menolak pembacaan tersebut dengan { deny: reason }, baris tersebut memuat alasan dari hook itu:

settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

Cari alasan di dalam tanda kurung tersebut di kode Anda:

• Kode Anda memuatnya: hook Anda menolak pembacaan tersebut. Buat hook Anda mengembalikan { value } ketika next.origin menunjukkan pembacaan milik Claude Code sendiri.
• Kode Anda tidak memuatnya: matikan mod Anda yang lain satu per satu. Jika organisasi Anda yang men-deploy sebuah mod, minta admin organisasi untuk mematikannya. Setelah setiap langkah:
  1. Mulai sesi dari shell Anda dengan claude --debug-file ./settings-read-2.log, diikuti flag yang digunakan saat sesi tersebut dimulai. Gunakan path baru setiap kali.
  2. Cari refused to the engine di file tersebut. Jika baris tersebut ada, matikan mod berikutnya. Jika tidak, mod terakhir yang Anda matikan adalah yang menolak pembacaan tersebut, jadi biarkan tetap mati.

Jika baris tersebut tetap ada saat tidak ada mod lain yang tersisa, tetapkan kunci yang dikembalikan hook Anda di file pengaturan. Nilai-nilainya tetap berlaku selama pembacaan ditolak.

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

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 hook-nya. Jika penyimpanan memecah modul, baris mengatakan reload failed, the previous version stays loaded: dengan alasan, dan versi terakhir yang berfungsi terus berjalan hingga Claude Code memuat ulang plugin berikutnya, misalnya saat Anda menjalankan /reload-plugins.

Langkah berikutnya

• Test a mod: tangkap masalah sebelum mencapai sesi
• Troubleshoot plugins: masalah dengan menginstal dan memuat plugin yang tidak spesifik untuk mod