> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

<h2 id="find-out-why-a-mod-does-nothing">
  Cari tahu mengapa mod tidak melakukan apa pun
</h2>

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`](/docs/id/plugins/mods/create#check-what-claude-code-reads-from-your-mod) 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](/docs/id/plugins/mods/create#ask-claude-for-a-mod) untuk mod yang ditulis Claude.
* **Sesi interaktif lainnya, seperti sesi yang menjalankan mod yang Anda instal dari marketplace**: [debug log](#read-the-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.

<h2 id="check-whether-mods-can-load">
  Periksa apakah mod dapat dimuat
</h2>

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](/docs/id/plugins/mods/troubleshoot#messages-from-the-built-in-guard).

<h2 id="the-mod-doesn’t-load">
  Mod tidak dimuat
</h2>

Tidak ada yang ditambahkan mod: tidak ada perintah, tidak ada gambar, dan tidak ada perubahan perilaku.

<h3 id="your-version-is-older-than-2-1-287">
  Versi Anda lebih lama dari 2.1.287
</h3>

`claude --version` mencetak versi lebih lama dari 2.1.287. Versi Anda mendahului mod yang diaktifkan secara default.

[Perbarui Claude Code](/docs/id/setup#update-claude-code).

<h3 id="the-mods-active-line-doesn’t-name-the-mod">
  Baris `mods active` tidak menyebutkan mod
</h3>

Tidak ada yang ditambahkan mod, dan baris [`mods active`](/docs/id/plugins/mods/overview#see-which-mods-a-session-loaded) 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](#refusal-messages) mencantumkan masing-masing. Jika log tidak memiliki baris seperti itu, kerjakan entri lain dalam grup ini.

<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">
  Jalankan `claude -p` mencetak `hooks module not loaded`
</h3>

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](#refusal-messages) mencantumkan masing-masing.

<h3 id="refusal-messages">
  Refusal messages
</h3>

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

<h3 id="messages-from-the-built-in-guard">
  Pesan dari built-in guard
</h3>

Pada mesin dengan pengaturan terkelola, atau untuk pengguna yang masuk dengan paket Team atau Enterprise, [built-in guard](/docs/id/plugins/mods/admin#know-what-happens-by-default) 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](/docs/id/plugins/mods/admin#install-your-organizations-mods), jadi milik Anda tidak dimuat | Debug log, dan transkrip dalam [sesi yang hot-reload direktori plugin](#find-out-why-a-mod-does-nothing) |
| `tried to lift a deny rule in your settings` | Hook [`tool.check`](/docs/id/plugins/mods/reference#tools) 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 |

<h3 id="validate-passes-and-lists-no-hooks-line">
  `validate` lulus dan tidak mencantumkan baris `hooks`
</h3>

`hooks/hooks.json` tidak memiliki kunci `modules`, atau kunci salah eja.

Tambahkan `"modules": ["./register.js"]`.

<h3 id="hooks-module-did-not-load">
  `hooks module did not load`
</h3>

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.

<h3 id="options-do-not-fit-plugin-json-userconfig">
  `options do not fit plugin.json userConfig`
</h3>

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`](/docs/id/plugins/components#user-configuration)-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`.

<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">
  Tidak ada mod yang dimuat di direktori yang Anda buka untuk pertama kalinya
</h3>

Anda belum menjawab prompt kepercayaan untuk direktori.

Mulai sesi interaktif di direktori itu dengan `claude`, dan terima prompt kepercayaan yang dibukanya.

<h3 id="no-installed-plugin-loads-at-all">
  Tidak ada plugin yang diinstal dimuat sama sekali
</h3>

Anda memulai Claude Code dengan `--safe-mode`.

Mulai tanpa flag.

<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">
  Hook dilewati atau mod dibongkar
</h2>

Mod dimuat, dan kemudian Claude Code melewati salah satu hooks-nya atau membongkarnya.

<h3 id="hook-skipped">
  `hook skipped`
</h3>

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](/docs/id/plugins/mods/reference#limits)-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.

<h3 id="it-crashed-the-hooks-worker">
  `it crashed the hooks worker`
</h3>

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.

<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">
  `mods that run in the hooks worker are off for this session`
</h3>

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.

<h2 id="a-tool-call-is-denied">
  Panggilan tool ditolak
</h2>

Mod dimuat dan hooks-nya berjalan, dan panggilan tool yang disentuhnya ditolak.

<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">
  `a hook changed this call's input after the model wrote it`
</h3>

Dalam mode auto, panggilan tool yang ditolak memberikan alasan ini. Hook mengubah input panggilan tool setelah [server-side classifier](/docs/id/permission-modes#server-side-classifier-review) meninjau, jadi tinjauan itu tidak mencakup apa yang akan berjalan. Hook dapat berupa [`tool.call`](/docs/id/plugins/mods/reference#tools) mod atau [`turn.step`](/docs/id/plugins/mods/reference#turns) hook, atau hook pengaturan [`PreToolUse`](/docs/id/hooks#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.

<h3 id="a-message-about-the-deny-rules-in-your-settings">
  Pesan tentang aturan deny di pengaturan Anda
</h3>

`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](#messages-from-the-built-in-guard).

<h2 id="a-drawing-doesn’t-appear-or-respond">
  Gambar tidak muncul atau merespons
</h2>

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

<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">
  Pane atau band kosong atau menampilkan konten biasa Claude Code
</h3>

[Tree](/docs/id/plugins/mods/interface#build-a-tree-from-elements) 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.

<h3 id="ui-open-runs-and-no-pane-appears">
  `$.ui.open` berjalan dan tidak ada pane yang muncul
</h3>

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](/docs/id/plugins/mods/interface#open-a-pane-at-the-right-time).

<h3 id="hotkeys-do-nothing">
  Hotkey tidak melakukan apa pun
</h3>

Pane Anda tidak memiliki fokus keyboard.

Tekan Ctrl+X kemudian Tab, atau klik pane. Buka dengan `focus: true` dari perintah.

<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">
  Gambar bekerja di terminal dan bukan di Desktop app
</h3>

Situs atau elemen tidak tersedia di sana.

Periksa tabel [render sites](/docs/id/plugins/mods/reference#render-sites) dan [elements](/docs/id/plugins/mods/reference#elements).

<h2 id="an-edit-or-a-value-is-lost">
  Edit atau nilai hilang
</h2>

Mod berjalan, dan perubahan yang Anda buat atau nilai yang disimpannya tidak ada.

<h3 id="your-edits-don’t-take-effect">
  Edit Anda tidak berlaku
</h3>

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.

<h3 id="a-value-resets-when-the-module-reloads">
  Nilai direset saat modul dimuat ulang
</h3>

Variabel tingkat modul diinisialisasi ulang pada setiap reload.

[Simpan nilai di `$.state` atau `$.store`](/docs/id/plugins/mods/interface#keep-state).

<h3 id="a-value-resets-after-/clear-/resume-or-/branch">
  Nilai direset setelah `/clear`, `/resume`, atau `/branch`
</h3>

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](/docs/id/plugins/mods/interface#load-a-saved-value-again-after-clear) dalam hook `classic.SessionStart`.

<h2 id="read-the-debug-log">
  Baca debug log
</h2>

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:

```bash theme={null}
claude --debug-file ./mod-debug.log --plugin-dir ./first-mod
```

Di terminal lain, ikuti file dan filter untuk nama mod Anda:

```bash theme={null}
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`:

```text theme={null}
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`](/docs/id/plugins/mods/api#show-something-without-starting-a-turn) 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.

<h2 id="next-steps">
  Langkah berikutnya
</h2>

* [Test a mod](/docs/id/plugins/mods/test): tangkap masalah sebelum mencapai sesi
* [Troubleshoot plugins](/docs/id/plugins/troubleshooting): masalah dengan menginstal dan memuat plugin yang tidak spesifik untuk mod