Claude Code breaking changes, updated weekly
Every verified Claude Code trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all Claude Code traps.
fg-0550· added 2026-10-24· last checked 2026-10-24
claude ultrareview refuses to run in scripts or CI after upgrading to 2.1.309
Symptom
claude ultrareview exits without running when no terminal is attached
Fix
Pass --trust-workspace in scripts. The flag takes no value, so put any PR number or base branch before it. Alternatively set CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1 in the environment.
fg-0551· added 2026-10-24· last checked 2026-10-24
Self-hosted runner checkout hook killed after 30 minutes and the session setup fails
Symptom
Session setup fails after a long checkout hook
Fix
Raise --checkout-hook-timeout-min to a larger number of minutes, or set it to 0 to disable the limit.
fg-0537· added 2026-10-17· last checked 2026-10-17
Fork subagents now on by default in claude -p, Agent SDK, desktop app and VS Code
Symptom
Headless or SDK runs spawn fork subagents that did not appear before
Fix
Turn fork subagents off if your workflow depends on the old behavior.
fg-0538· added 2026-10-17· last checked 2026-10-17
Large requests to api.anthropic.com are now gzip compressed even with telemetry disabled, breaking some proxies
Symptom
A proxy or inspection layer in front of api.anthropic.com rejects or cannot read request bodies after upgrading
Fix
Disable gzip request bodies, or make the proxy accept gzip.
fg-0487· added 2026-10-15· last checked 2026-10-15
claude -p --output-format stream-json exits with 'requires --verbose'
Symptom
Error: When using --print, --output-format=stream-json requires --verbose
Fix
Add --verbose whenever --output-format stream-json is used with -p.
fg-0491· added 2026-10-15· last checked 2026-10-15
Plugin hook fails with 'No such file or directory' when the install path contains a space
Symptom
/bin/sh: /Users/Jane: No such file or directory
Fix
Wrap the variable itself in double quotes inside the command string, or use exec form with args so each path is one argument. claude plugin validate warns about an unquoted variable.
fg-0488· added 2026-10-15· last checked 2026-10-15
Exit code 2 from a PermissionRequest hook does not deny the permission
Symptom
The permission flow continues unchanged after the hook exits 2
Fix
Print a hookSpecificOutput decision with behavior deny and exit 0, or move the check to PreToolUse, where exit 2 blocks the call.
fg-0492· added 2026-10-15· last checked 2026-10-15
Plugin hooks never fire because hooks.json lacks the top-level "hooks" key
Symptom
Plugin is enabled but none of its hooks run
Fix
Wrap the event map in a hooks key, then run claude plugin validate on the plugin folder.
fg-0493· added 2026-10-15· last checked 2026-10-15
Plugin skills, commands, or hooks are missing because they sit inside .claude-plugin/
Symptom
The plugin installs and is enabled, but its skills and commands do not appear
Fix
Move every component folder to the plugin root, bump the version in plugin.json so the installed cache refreshes, and validate.
fg-0494· added 2026-10-15· last checked 2026-10-15
Read deny rule like Read(/private/**) in user settings does not protect that absolute path
Symptom
Claude still reads files under the absolute path named in a deny rule
Fix
Write absolute rules with // and home rules with ~/ in user settings, and test them with a read attempt.
fg-0489· added 2026-10-15· last checked 2026-10-15
.mcp.json servers stay 'Pending approval' and enableAllProjectMcpServers in the repo is ignored
Symptom
claude mcp list shows the project server as Pending approval (run claude to approve)
Fix
Run claude once in the folder and accept the trust dialog and the server prompt, or put the approval in your user settings, managed settings, or a --settings argument, which apply even in an untrusted folder.
fg-0484· added 2026-10-15· last checked 2026-10-15
claude mcp add treats the MCP server's own flags as Claude Code options
Symptom
error: unknown option '--port'
Fix
Put Claude Code options such as --transport, --env, and --scope before the server name, then -- and the server command with its own flags.
fg-0481· added 2026-10-15· last checked 2026-10-15
Claude Code auto memory forgets entries once MEMORY.md passes 200 lines or 25KB
Symptom
Facts saved to auto memory are unknown in a new session
Fix
Keep MEMORY.md as an index with one short line per entry and move detail into topic files the index points to. Merge or delete stale entries.
fg-0482· added 2026-10-15· last checked 2026-10-15
Claude Code ignores AGENTS.md when the repository also has a CLAUDE.md
Symptom
Rules written in AGENTS.md are not followed while CLAUDE.md rules are
Fix
Import AGENTS.md from CLAUDE.md so one file serves Claude Code and the other agents, or set Project instructions to claude-md-and-agents-md in /config (or pluginConfigs in ~/.claude/settings.json) so both load. Update Claude Code first.
fg-0480· added 2026-10-15· last checked 2026-10-15
claude --bare -p fails to authenticate although the normal session is signed in with Pro or Max
Symptom
A --bare run fails on authentication while the same command without --bare works
Fix
Set ANTHROPIC_API_KEY to a key created in the Claude Console, or supply an apiKeyHelper in the --settings JSON.
fg-0485· added 2026-10-15· last checked 2026-10-15
CLAUDE.md @import of a path that contains a space silently loads nothing
Symptom
Instructions in the imported file are ignored with no warning
Fix
Put a backslash before each space in the path, or rename the folder. Imports inside backticks or code blocks are skipped on purpose.
fg-0486· added 2026-10-15· last checked 2026-10-15
claude -p in a freshly cloned repo runs its hooks and .mcp.json servers without asking
Symptom
Hook commands from the repo's .claude/settings.json run in CI
Fix
On untrusted code or in CI use --bare, which skips hooks, MCP servers, plugins, skills, auto memory, and CLAUDE.md, and pass what the run needs with flags.
fg-0483· added 2026-10-15· last checked 2026-10-15
Claude Code PreToolUse hook exits 1 but the tool call runs anyway
Symptom
PreToolUse:Bash hook error notice with 'Failed with non-blocking status code:' and the command still runs
Fix
Exit 2 with the reason on stderr to block, or return a JSON decision. On Claude Code v2.1.295 or later, set onFailure to block on policy hooks so a broken or missing script fails closed; older versions ignore the field.
fg-0490· added 2026-10-15· last checked 2026-10-15
Permission rules on Write(path), Glob(path), or a .claudeignore file are accepted but never enforced
Symptom
Claude writes into a folder covered by a Write(docs/**) deny rule
Fix
Use Edit(path) for anything that writes and Read(path) for anything that reads or lists, and move .claudeignore entries into Read deny rules.
fg-0007· added 2026-10-13· last checked 2026-10-13
Edits to a local Claude Code plugin never show up
Symptom
The plugin behaves like the old version after editing its source
Fix
Bump the version in .claude-plugin/plugin.json, update the marketplace and the plugin, then restart or reload plugins.
fg-0005· added 2026-10-07· last checked 2026-10-07
Auto mode refuses to edit ~/.claude/settings.json or copy secrets even when asked
Symptom
Denied as Self-Modification when adding allow rules
Fix
Have the user run the change: give a ready-to-run command that backs up the file first, then continue after it has run. Keep secrets in a chmod 600 file the scripts read at runtime.
fg-0010· added 2026-08-03· last checked 2026-08-03· stale, may be out of date
MCP servers with write access to one project load in every directory
Symptom
Tools for one client's systems are available in an unrelated folder
Fix
Register servers under each project's own block and keep the top-level block empty unless a server truly belongs everywhere.
fg-0008· added 2026-08-03· last checked 2026-08-03· stale, may be out of date
Fixing MCP credentials in ~/.claude.json has no effect until a restart, and edits can be lost
Symptom
The MCP keeps using the old credentials after the file is fixed
Fix
Edit the file with Claude Code closed, or restart afterwards and confirm the change survived.
fg-0009· added 2026-07-31· last checked 2026-07-31· stale, may be out of date
MCP server fails with placeholder credentials although the global config is correct
Symptom
Unknown username
Fix
Check the block under projects["/current/working/dir"].mcpServers first and fix the env values there.
Have your agent check Claude Code changes before it codes