---
title: "Claude Code Isn't Working: Diagnose by Symptom"
description: "Stop guessing. Work out which layer is broken — install, config, permissions, context, or the model — before you change anything."
source: "https://claudeflow.so/guides/troubleshooting-claude-code/"
---

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.

    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.

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

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

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

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

  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.

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

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

   ```bash
   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](/guides/config-not-applying/) 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](/guides/config-not-applying/) |
| 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:

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

    ```bash
    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

  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