Claude Code Mod Not Working? How to Fix It

When a mod or one of its hooks fails, Claude Code skips it and carries on, so a broken mod usually just looks like it does nothing. Start with two checks, then match your message below.

Last checked against the official docs: 2026-10-02

Two quick checks

Can mods load at all? Run claude plugin test in a folder that holds no mod. no hooks module to load means mods can load; anything about mods being turned off means a setting or policy is blocking them.
What does Claude Code read from your mod? Run claude plugin validate ./your-mod. It catches misspelled events, a bad manifest and unreadable modules without starting a session.

The mod doesn't load

What you see	What it means / fix
`claude --version is older than 2.1.287`	Your version predates mods being on by default. Update Claude Code.
`hooks modules are turned off here`	Shown by claude plugin test. disableAllHooks in your settings, or your organization's policy, is blocking mods.
`hooks modules are turned off in this process`	Anthropic has switched installed mods off remotely. No local setting turns them back on.
`only managed plugins and built-in plugins run`	allowManagedHooksOnly is set, or disableAllHooks is set somewhere other than managed settings.
`…in this mode (--bare)`	You started Claude Code with --bare. Start without it.
`another plugin of that name loads first`	Two plugins share a name. Rename yours.
`mods are limited to your organization's by policy`	Your organization only allows its own mods (allowManagedModsOnly).
`validate passes but lists no hooks line`	hooks/hooks.json has no modules key or it is misspelled. Add "modules": ["./register.js"].
`hooks module did not load: …`	Your module's top-level code threw. The reason names the file and line.
`No mod loads in a folder you just opened`	You haven't accepted the trust prompt for that folder. Run claude there and accept it.
`No installed plugin loads at all`	You started with --safe-mode. Start without it.

The mod loads, but something fails

What you see	What it means / fix
`… hook skipped: …`	A hook threw, ran past its time limit, or returned the wrong shape. Fix the error named after the colon.
`registered /x but no command.run hook answered it`	No command.run hook matched that command name, or the hook passed it on with next(e).
`was unloaded: it crashed the hooks worker`	A hook blocked the shared worker thread, for example a loop that never awaits.
`mods that run in the hooks worker are off for this session`	The worker crashed three times. Run /reload-plugins to load mods again.
`a hook changed this call's input after the model wrote it`	In auto mode, a hook rewrote a tool call after it was reviewed. Turn the mod off or approve the call yourself.
`Pane or band is empty`	The element tree your hook returned didn't validate; the transcript or debug log gives the reason.
`Hotkeys do nothing`	The pane doesn't have focus. Press Ctrl+X then Tab, or click it.
`Your edits don't take effect`	You're editing an installed (cached) copy. Develop with --plugin-dir instead.
`A value resets on reload`	Module-level variables reset on every reload. Keep values in $.state or $.store.

Read the debug log

For a mod installed from a marketplace, failure messages only go to the debug log. Start Claude Code with a log file and filter it for your mod's name:

claude --debug-file ./mod-debug.log --plugin-dir ./my-mod

# in another terminal
tail -f ./mod-debug.log | grep my-mod

A mod that loaded gets a line listing the events it handles. A mod loaded with --plugin-dir shows its name followed by @inline. To write your own debug lines, call $.ui.log('message', { to: 'debug' }).

New to mods? Start with installing one or writing your first.

Source: Troubleshoot a mod, checked 2026-10-02.