Claude Code acting up after a config change, how to find the cause

Everything was running. Then you added a hook, installed a skill, entered a new MCP server, and suddenly Claude Code stutters. Tools do not load, startup takes forever, a prompt gets answered strangely or the session drops. And you no longer know which of your ten changes from the past week did it. That is the most annoying class of bug, because you have no clear symptom, just the feeling that something in your setup is off.

Since version 2.1.169 there is a built-in tool for exactly this. Safe mode. It starts Claude Code with every customization switched off, and from there you work your way back layer by layer. Same method as safe mode in Windows, just for your CLI. I will walk through the ten steps that tell you what is broken.

1. Check the version first

Safe mode exists from Claude Code 2.1.169. If your version is older, the flag is missing and you have to use the old sledgehammer method, moving config files aside by hand. Check first:

claude --version

Below that? Update first. How to do that cleanly is in the playbook Claude Code update strategy. Then come back here.

2. Start in safe mode

This is the one command everything revolves around:

claude --safe-mode

Alternatively as an environment variable, if you want it for a whole shell session:

CLAUDE_CODE_SAFE_MODE=1 claude

Safe mode switches off all your customizations. Concretely: your CLAUDE.md, all plugins, all skills, all hooks and all MCP servers. You get a bare Claude Code, the way it would run fresh after installation. None of your own stuff is active.

3. Reproduce the error in safe mode

Now do exactly what went wrong before. Same prompt, same file, same bash command. Two outcomes are possible, and both tell you something.

If the error is gone in safe mode, it is one of your customizations. Good, that is the common case, and from step 4 you narrow down which one. If the error persists in safe mode too, it is not your config but Claude Code itself, your installation or your network. Then jump straight to step 9.

4. One layer at a time, not everything at once

The reflex now is to switch everything back on simultaneously and look. Do not do that. You end up exactly where you started and know nothing again. The order I use goes from outside in, from what breaks most easily to what is least often at fault:

MCP servers, then hooks, then skills, then plugins, then CLAUDE.md. After each layer you test again. The moment the error reappears, you have your culprit.

5. Start with the MCP servers

MCP servers are the most common source of failure because they start external processes, need tokens and talk over the network. Start Claude Code normally, but with only the MCP servers you suspect active. If you have many, comment out all but one in your MCP config and work your way up.

If the error comes back with a particular server, you have it. What to do then is covered in detail in the playbook Debugging MCP when nothing works. Often it is an expired token or a server that does not start at all.

6. Then the hooks

Hooks fire on tool calls and can block a session if a hook script throws an error or hangs. Switch your hooks back on one at a time. A hook that aborts with exit code 2 blocks the action, which is intended, but a hook with a bug in the script may block everything.

If a hook is the culprit, go to the playbook Debugging hooks when nothing fires. It covers both the reverse case, hook does not fire, and this one, hook fires too much.

7. Skills, and the trick with bundled skills

Skills only load when Claude considers them relevant, so normally they cost almost no context. Still, a broken skill definition can cause problems. Switch your own skills in the .claude/skills/ directory back on one at a time.

Since 2.1.169 there is one more special case. Claude Code ships its own bundled skills, workflows and built-in slash commands. If you suspect one of those is interfering, you can hide them with a setting without touching your own:

{
  "disableBundledSkills": true
}

Or as environment variable CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1. If the error disappears with that, it was a bundled skill and not yours. More on trigger behaviour in the playbook Skill trigger debugging.

8. Plugins and CLAUDE.md last

Plugins often pull hooks, skills and MCP servers along in one package, which is why they come late. Activate them one at a time. A plugin from a foreign ZIP or URL is a good suspect, especially if you installed it recently.

That leaves CLAUDE.md. It rarely causes hard trouble, but it can nudge Claude in a direction you did not want, or it has grown so long that it eats half the context. Recently the warning that CLAUDE.md is too long scales with the model's context window, so you get a hint when it crosses the line. If that was your symptom, shorten it or move parts into referenced files.

9. If the error persists in safe mode too

Then it is not your config. Three suspects remain. First the installation itself, an update that half completed or a broken binary. A clean update or a reinstall often helps here. Second the network, especially if you sit behind a proxy or VPN or the API is currently overloaded. Third a genuine bug in the version you are running.

For overload errors, a fallback model chain is worth it so Claude Code automatically moves to the next model when one is saturated. How that works is in the companion playbook Fallback models against overload.

10. Reset cleanly and write it down

You have the culprit. Now take safe mode back out and start normally, with the one change fixed or removed. Important, and I forget this constantly myself: write down briefly what it was. An expired token, a typo in the hook path, a skill that collided with another. Next time that saves you the whole round, because you have the suspicion right away.

Safe mode does not replace the feature-specific debug playbooks. It is the stage before. First you narrow down with safe mode which layer has the problem, then you go deep with the matching playbook. If you want the bigger picture, the playbook Avoiding tool sprawl helps, because most of these errors simply come from installing too much at once.

What next

If your error was an overloaded or unavailable model, continue with Fallback models against overload. If it was an MCP server, then Debugging MCP when nothing works. And if you are generally interested in building a setup that breaks less often, look at level 4 lesson Hooks and skills.

Source

• Claude Code changelog, version 2.1.169 (--safe-mode, CLAUDE_CODE_SAFE_MODE, disableBundledSkills): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Claude Code docs: https://code.claude.com/docs/en/changelog