Troubleshooting

This page is for problems that show up once Claude Code is installed and running: the session is slow, eats memory, freezes, renders badly or can't find files. If you're stuck earlier than that, or the symptom is a specific error message, start from the routing table below instead.

Start in the right place

When you can't tell which row applies, let Claude Code diagnose itself first:

• /doctor inside a session checks the installation, settings files, extensions and context usage, and proposes fixes it applies after you confirm.
• claude doctor from your shell does a read-only version of the same checks without starting a session. Use it when claude won't start.
• /mcp shows whether each MCP server is connected.

High CPU or memory

Long sessions in large repositories are the usual culprit. Work through these in order:

1. Shrink the conversation. Run /compact. If it answers Not enough messages to compact., the conversation is only one or two turns long and something big (often a single huge paste) is filling it, so /clear is the better move.
2. Restart between big tasks. A fresh process is cheaper than a bloated one. Your conversation survives: claude --continue picks up the most recent session in a new process.
3. Keep build output out of the way. Add heavy generated directories (dist/, target/, .next/) to .gitignore so searches skip them.
4. Rule out your customisations. Start with claude --safe-mode, which turns off plugins, MCP servers, hooks, skills and CLAUDE.md for that session. If the problem disappears, one of them is responsible; Debug your configuration shows how to find which.

Claude Code warns you when a session's heap passes 2.5GB. The warning clears once usage falls back under that line. Restarting and running claude --continue is the reliable fix; outside fullscreen rendering, /compact also releases memory.

Capture a heap dump

If memory stays high, type /heapdump in full (it is deliberately hidden from the command menu). It writes two files to ~/Desktop, or your home directory on Linux machines without a Desktop folder:

The command also prints a summary showing total memory, how much is in the JS heap versus native memory, and any leak indicators such as fast growth or an unusual number of open handles.

• To report it, open an issue on the Claude Code GitHub repository and attach only the diagnostics JSON.
• To dig in yourself when most memory is in the JS heap, load the snapshot in Chrome DevTools (Memory, then Load) and sort by retained size.
• If most memory is native, the snapshot can't show it. Put the leak indicators from the summary into your report instead.

Warning: Never attach a .heapsnapshot to a public issue. Treat it like a credentials file.

The context keeps refilling: "Autocompact is thrashing"

Autocompact is thrashing: the context refilled to the limit... means compaction worked, but a file or tool result immediately filled the window again, several times in a row. Claude Code stops rather than burn API calls in a loop. To get out of it:

1. Ask Claude to read the large file in pieces, for example one function or a line range.
2. Run /compact with a focus that discards the bulky output, such as /compact keep the migration plan and the failing test only.
3. Push the heavy reading into a subagent, which has its own context window.
4. Run /clear if you don't need the earlier conversation.

If it happens again straight after /clear, run /context and compare the Messages row with everything above it. If Messages is the biggest, a file or tool output in the new conversation is the problem, so repeat steps 1 to 3. If the other rows add up to more, your startup load (memory files, MCP tool definitions, skills) is too heavy; see Prompt is too long for how to trim it.

Long tables are cut off

A Markdown table over 200 rows shows its first 200 rows plus a … N more rows not shown line. Only the display is capped. /copy still copies every row, and asking Claude to write the table to a file is usually more useful than scrolling a terminal anyway. Versions before v2.1.208 rendered every row, which could stall when you resumed a session containing a huge table.

Claude Code hangs or freezes

Press Ctrl+C to cancel the current operation. If nothing responds, close the terminal. You don't lose anything: run claude --resume in the same directory and choose the session to carry on.

Garbled text in an editor's terminal

Boxes, smeared characters or wrong glyphs in the integrated terminal of VS Code, Cursor or Devin Desktop usually come from the terminal's GPU renderer. Run /terminal-setup and it sets terminal.integrated.gpuAcceleration to "off" for you, or change that setting yourself and reload the window. Terminal configuration lists everything else /terminal-setup touches.

Mouse wheel scrolls too slowly in fullscreen

In fullscreen rendering, Claude Code handles scrolling itself. If each notch moves too few lines, run /scroll-speed to raise and save the lines-per-notch value, or set CLAUDE_CODE_SCROLL_SPEED. Neither applies in the JetBrains terminal, which uses its own scroll handling. PgUp and PgDn move half a screen at a time, and /tui default switches back to the classic renderer if you'd rather use your terminal's native scrollback.

Copying to the clipboard

Inside the sandbox

With sandboxing on, pbcopy, xclip and wl-copy often can't reach the system clipboard from a sandboxed Bash command, and adding them to excludedCommands doesn't fix that by itself. The dependable route is to have Claude print the content in its reply and then run /copy. That writes from the Claude Code process, not a sandboxed command. It can copy a single code block, and it also saves what it copied to a file and prints the path, which is handy when the clipboard can't be reached at all.

Over SSH

On a remote machine, Claude Code can't run your local clipboard tool. Outside tmux, selecting text in fullscreen or running /copy sends the text as an OSC 52 escape sequence and leaves it to your terminal to accept. /copy says Copied to clipboard either way, and the selection notice reads sent N chars via OSC 52.

Some terminals ignore OSC 52. iTerm2 needs Settings > General > Selection > Applications in terminal may access clipboard switched on, and macOS Terminal.app doesn't support it at all. Workarounds:

• Hold your terminal's native-selection modifier while dragging (Fn in Terminal.app, Option in iTerm2), then copy normally. Fullscreen rendering lists the key for other terminals.
• Set CLAUDE_CODE_DISABLE_MOUSE=1 on the remote machine so your terminal owns selection for the whole session.

Search, @-mentions or custom agents can't find files

The Search tool, @file mentions, custom agents and custom skills all rely on a bundled ripgrep binary. If that binary can't run on your system, install ripgrep yourself:

Then tell Claude Code to use the system copy by setting USE_BUILTIN_RIPGREP to 0, either exported in your shell or in a settings file:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Run claude doctor afterwards. The Search line should show the path to your system rg instead of OK (bundled).

Thin results on WSL

When a project lives on the Windows filesystem (/mnt/c/...) and you run Claude Code inside WSL, cross-filesystem reads are slow enough that searches return fewer matches than they should. claude doctor still reports Search as OK, which makes this one easy to miss. Options, best first:

1. Move the repository into the Linux filesystem, somewhere under /home/.
2. Narrow the search: "find the token refresh logic in packages/auth" beats "find the token refresh logic".
3. Run Claude Code natively on Windows instead of through WSL.

Getting more help

1. Run /doctor, and /mcp if servers are involved.
2. Use /feedback to send the problem, with your transcript, straight to Anthropic.
3. Search the GitHub issues for a known bug.
4. Ask Claude itself. It can look up how its own features work.

Account, billing and subscription problems go to Anthropic support rather than GitHub: sign in at claude.ai (or platform.claude.com for Console accounts), click your initials in the bottom left and choose Get help.

Related

• Troubleshoot installation and login
• Debug your configuration
• Error reference
• Context window
• Fullscreen rendering