Перейти к основному содержимому

Troubleshooting Claude Code

Средний
What you'll learn
  • Route any Claude Code problem to its fix in one step, using a symptom table
  • Run the two diagnostic commands that solve most setup issues before you debug anything by hand
  • Isolate whether a plugin, MCP server, or hook is the real cause
  • Fix the four classic runtime failures: high memory, hangs, compaction thrashing, and search finding nothing
  • Collect the right evidence before filing a bug report

The big idea​

Almost every Claude Code problem is one of two kinds, and they have completely different fixes:

  • Your setup is wrong — a plugin, an MCP server, a hook, a settings file, a missing binary. The fix is configuration.
  • The session is under strain — the context window is full, a huge file blew up memory, the terminal can't render. The fix is hygiene.

Guessing which one you have is where people lose an afternoon. The table below skips the guessing.

:::tip Different kind of "weird"? This page is about the tool misbehaving — it won't start, it hangs, search finds nothing. If the model is misbehaving — it made up a fact, forgot an instruction, refused something reasonable — that's a different page: Why Did Claude Do That? :::

Start here: symptom → where to go​

Find your symptom. Don't read the rest of the page.

SymptomGo to
command not found, install fails, EACCES, PATH or TLS errorsOfficial: install & login
Login loops, OAuth errors, 403 Forbidden, "organization disabled"Official: login & authentication
Settings not applying, hooks not firing, MCP servers not loadingIsolate your config below
API Error: 5xx, 529 Overloaded, 429, validation errorsErrors & Rate Limits
model not found / "you may not have access to it"Current Models & Pricing
VS Code or JetBrains not detecting ClaudeIDE Integrations
High CPU or memoryMemory and CPU below
Hangs, freezes, unresponsiveHangs and freezes below
Autocompact is thrashingCompaction thrashing below
Search, @file, agents, or skills not finding filesSearch finds nothing below
Boxes, smears, or wrong glyphs in an IDE terminalGarbled terminal text below

The two commands to run first​

Before you debug anything by hand, run the built-in checkup. It diagnoses your installation, settings, extensions, and context usage — and proposes fixes it can apply after you confirm.

Guided walkthrough1 of 3
  1. /doctor (its alias is /checkup) inspects your installation, settings, extensions, and context usage, then offers to apply the fixes it can. This alone resolves most setup complaints.

Diagnose a broken setup

# inside a session
/doctor

# if the session won't start at all
claude doctor

# check MCP server status
/mcp

Isolate your config​

If settings aren't applying, hooks aren't firing, or something is just off, the question is never "what's broken" — it's which of your customizations is broken. Answer it by removing all of them at once.

--safe-mode starts Claude Code with every customization disabled: no plugins, no MCP servers, no hooks.

Test against a clean configuration

claude --safe-mode

This gives you a clean binary result:

Once you know it's a customization, bisect: re-enable them in groups until the problem returns. The suspects, in rough order of how often they're the culprit, are MCP servers, hooks, plugins, and settings.

Pro tip
  • --safe-mode is also the right first move for mysterious slowness, not just outright breakage. A chatty MCP server is a very common cause of both.

Memory and CPU​

Claude Code works with most environments but can consume real resources on large codebases. Work through these in order — they're sorted cheapest-first.

Guided walkthrough1 of 5
  1. Run /compact to shrink the context. A bloated context window is the single most common cause of a heavy session. See /docs/claude-code/context-management.

The /heapdump breakdown reports resident set size, JS heap, array buffers, and unaccounted native memory. That split is the useful part: it tells you whether growth is in JavaScript objects or down in native code. To inspect what's holding memory alive, open the .heapsnapshot file in Chrome DevTools under Memory → Load.

Hangs and freezes​

If Claude Code stops responding:

Guided walkthrough1 of 3
  1. Press Ctrl+C. This aborts whatever is running without killing the session.
Pro tip
  • The fear of losing a long conversation is why people wait out a hang instead of killing it. Don't — claude --resume in the same directory brings the session back.

Compaction thrashing​

This error looks alarming and is actually a protection:

Autocompact is thrashing: the context refilled to the limit...

It means automatic compaction succeeded — and then a file or tool output immediately refilled the entire context window, several times in a row. Claude Code stops retrying rather than burn API calls on a loop that isn't making progress.

The cause is almost always one oversized thing being read whole. Pick the fix that matches your situation:

SituationFix
One huge file is the problemAsk Claude to read a line range or a single function instead of the whole file
The context has a large output you no longer need/compact with a focus that drops it
The big read is genuinely necessaryMove it to a subagent so it burns a separate context window
The earlier conversation no longer matters/clear

Compact with a focus that drops the bloat

/compact keep only the plan and the diff

The subagent option is the one people forget, and it's often the best: a subagent reads the giant file in its context and returns only the conclusion to yours. See Context Management and Subagents.

Search finds nothing​

If the Search tool, @file mentions, custom agents, or custom skills aren't finding files that you know exist, the bundled ripgrep binary probably can't run on your system. The fix is to install your platform's own ripgrep and tell Claude Code to use it.

Guided walkthrough1 of 3
  1. macOS: brew install ripgrep — Ubuntu/Debian: sudo apt install ripgrep — Alpine: apk add ripgrep — Arch: pacman -S ripgrep — Windows: winget install BurntSushi.ripgrep.MSVC

Fix search on macOS

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

The WSL exception​

On WSL, incomplete search results are usually not a broken binary. Reading across the Windows/Linux filesystem boundary carries a disk performance penalty, so search returns fewer matches than expected. Search still works — it just under-delivers.

Watch out
  • On WSL, claude doctor reports Search as OK even while results are incomplete. A green checkup does not rule this out — that's exactly what makes it hard to diagnose.

Three ways out, best first: move the project onto the Linux filesystem (/home/) rather than /mnt/c/; run Claude Code natively on Windows instead of through WSL; or narrow your searches so fewer files are scanned — "Search for JWT validation logic in the auth-service package" beats "find the auth code."

Garbled terminal text​

Characters rendering as boxes, smears, or the wrong glyphs inside the VS Code, Cursor, or Devin Desktop integrated terminal is a GPU renderer problem, not a font or encoding problem.

Fix garbled glyphs in an IDE terminal

/terminal-setup

That sets terminal.integrated.gpuAcceleration to "off". You can set it by hand in your editor settings and reload the window instead — same result.

Large tables get cut off​

A Markdown table over 200 rows renders its first 200 followed by a … N more rows not shown line. This is a display cap only — the full table is still in the conversation, and /copy copies every row. For a table too large to read in a terminal at all, ask Claude to write it to a file.

Filing a good bug report​

If nothing here fits, report it — but bring evidence. A report that says "it's slow" gets nowhere; one with a heap snapshot and a --safe-mode result gets fixed.

Guided walkthrough1 of 4
  1. Capture what the checkup says and which MCP servers are actually loaded. Half of reported bugs are answered here.
Key takeaways
  • Run /doctor (alias /checkup) first — from your shell as claude doctor if the session won't start. It diagnoses installation, settings, extensions, and context usage, and can apply fixes.
  • claude --safe-mode disables all customizations at once. Whether the problem survives it is the single most informative fact you can gather.
  • High memory: /compact, restart between tasks, .gitignore build dirs, then --safe-mode, then /heapdump for evidence.
  • A hang is not a lost conversation — Ctrl+C, then restart the terminal, then claude --resume in the same directory.
  • Autocompact thrashing means one oversized read refills the window. Read in chunks, /compact with a focus, or delegate the read to a subagent.
  • Search finding nothing usually means the bundled ripgrep can't run: install your platform's ripgrep AND set USE_BUILTIN_RIPGREP=0. On WSL it's a filesystem-boundary penalty instead — and claude doctor still reports Search as OK.

Check yourself

0/5
  1. Hooks aren't firing and settings seem to be ignored. What's the single most informative thing to try?
  2. Claude Code hangs mid-task and Ctrl+C doesn't help. You close the terminal. What happens to your conversation?
  3. You see 'Autocompact is thrashing: the context refilled to the limit...'. What actually happened?
  4. You installed ripgrep with brew because @file mentions found nothing, but search is still broken. What did you miss?
  5. On WSL, search returns fewer matches than expected but claude doctor reports Search as OK. What's going on?

Next​