Claude Code Isn't Working: Diagnose by Symptom

Every “Claude Code not working” article gives you the same five fixes: reinstall, update, check your API key, restart the terminal, clear the cache. Sometimes one of them lands. When it does, you learned nothing, and you will be back here in a month.

The problem is that “not working” is five different failures wearing the same coat. A tool that never launches and a tool that launches but ignores your CLAUDE.md have nothing in common except your frustration. Fix the diagnosis and the fix falls out for free.

The five layers

Claude Code fails at one of five layers, and they fail in a fixed order. A broken layer makes every layer above it look broken too — which is exactly why shotgunning fixes wastes your afternoon.

1. Install

The binary is missing, the wrong version, or shadowed by another one on your PATH. Symptom: it doesn’t start, or --version disagrees with what you installed.

2. Auth & connectivity

It starts but cannot reach the model. Symptom: it hangs, or every request errors identically regardless of what you ask.

3. Config

It runs, but your settings are not the settings it loaded. Symptom: a change you made has no visible effect.

4. Permissions

It runs with your config, but refuses actions or asks constantly. Symptom: prompts you expected to be silent, or a tool that never fires.

5. Context

Everything works and the output is still wrong. Symptom: it forgets, contradicts your conventions, or answers about the wrong file.

Do not skip levels

If layer 1 is broken, layers 3 to 5 will produce misleading evidence. Work upward, and stop at the first layer that fails — the layers above it are probably fine.

Diagnose in order

1. Ask the tool about itself first.

   Before you touch a config file, get the tool’s own account of its state. This one command is the cheapest information you will get all session.

   claude doctor

   It checks the installation and reports what it finds. If this is unhappy, you are at layer 1 and nothing below matters yet.

2. Confirm you are running the binary you think you are.

   A stale global install shadowing a newer one is the single most common false alarm.

   claude --version
   which -a claude   # every `claude` on your PATH, in resolution order

   More than one line from which -a means the first one wins, and it may not be the one you upgraded. That is layer 1, and it is not a Claude Code bug.

3. Watch it work.

   If it launches but misbehaves, stop reading config and start reading logs. Debug output shows what it loaded, what it called, and where it stopped.

   claude --debug

   Reproduce your problem with this running. The line immediately before things go wrong is usually the answer.

4. Check what config actually loaded.

   Not what you wrote — what it read. Inside a session:

   /status

   If the settings shown here are not the settings you edited, you are at layer 3, and you want the config precedence guide rather than another reinstall.

5. Check permissions explicitly.

   If tools are being refused or you are drowning in prompts, look at the rules rather than inferring them from behaviour:

   /permissions

6. Only now suspect context.

   Layers 1 to 4 are mechanical: they are either right or wrong, and you can prove which. Layer 5 is not. If everything above checks out and the output is still poor, the problem is what the model was given, not whether the tool works.

Symptom → layer

Use this to jump straight to the right layer instead of starting from the top every time.

What you see	Layer	Start here
Command not found, or wrong version	Install	which -a claude, then reinstall
Hangs on every request	Auth & connectivity	claude --debug, check network and credentials
Every request fails identically	Auth & connectivity	claude --debug
Edited settings, nothing changed	Config	Config precedence
Hooks never fire	Config	Settings file location and JSON validity
Constant permission prompts	Permissions	/permissions
A tool is never used	Permissions	/permissions, then MCP status with /mcp
Ignores your conventions	Context	CLAUDE.md content and placement
Forgets earlier work mid-session	Context	Session length and compaction
Confidently edits the wrong file	Context	What you actually pointed it at

Common mistakes

Reinstalling as a first move. Reinstalling resets layer 1. If your problem was layer 3, you have destroyed your diagnosis and kept your bug — and now you cannot tell whether the config was ever the issue.

Editing settings while a session is open. Some settings are read when the session starts. Change the file, then start a fresh session before concluding the change did nothing.

Assuming invalid JSON will announce itself. A settings file with a trailing comma or a stray quote can be skipped quietly. Validate it before you spend an hour on the contents:

macOS / Linux

python3 -m json.tool .claude/settings.json > /dev/null && echo "valid"

Any platform with Node

node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'));console.log('valid')"

Blaming the model for a context problem. “It gave me a bad answer” and “it was given bad inputs” look identical from the outside. Switching models on a layer 5 problem changes the flavour of the wrong answer, not its correctness.

Changing two things at once. If you fix the install and rewrite your settings and it starts working, you still do not know what was broken. Next time it breaks, you are back to zero.

Checklist

Keep this next to you. Work down, stop at the first failure.

• claude doctor reports a healthy installation
• claude --version matches what you intended to install
• which -a claude returns exactly one path you recognise
• A trivial prompt gets a response — auth and connectivity are fine
• /status shows the settings you actually edited
• Every settings file in play is valid JSON
• /permissions matches what you expect to be allowed and denied
• The session was restarted after the last config change
• Only then: look at CLAUDE.md, session length, and what you pointed it at

Write down which layer it was

Keep a note of the layer each time something breaks. After a handful of incidents the pattern is obvious, and it is almost never the layer people reinstall first.

Where to go next

Your config isn't applyingLayer 3 in full: the precedence chain, and how to prove which file won.

settings.json, field by fieldOnce you know which file wins, this is what belongs inside it.

Official troubleshooting referenceAnthropic's canonical page. Use it for the exhaustive error list; use this guide for the order to check things in.