Troubleshooting

Fix high CPU or memory usage, hangs, auto-compact thrashing, and search problems in Claude Code, and find the right page for other issues.

This page covers performance, stability, and search problems once Claude Code is running. For other issues, start with the page that matches where you're stuck:

If you're not sure which applies, run /doctor inside Claude Code for an automated check of your installation, settings, extensions, and context usage; it proposes fixes it can apply after you confirm. If claude won't start at all, run claude doctor from your shell instead. Run /mcp to check MCP server status.

Performance and stability

These sections cover issues related to resource usage, responsiveness, and search behavior.

High CPU or memory usage

Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues:

1. Use /compact regularly to reduce context size. If it returns Not enough messages to compact., the conversation has too few turns to summarize; that can happen even with a full context when a single large paste filled it
2. Close and restart Claude Code between major tasks
3. Consider adding large build directories to your .gitignore file
4. Restart with claude --safe-mode to check whether a plugin, MCP server, or hook is the source. It disables all customizations for the session; if usage drops, see Debug your configuration to find which one

If memory usage stays high after these steps, run /heapdump to write two files to ~/Desktop: a JavaScript heap snapshot named <session-id>.heapsnapshot and a memory breakdown named <session-id>-diagnostics.json. The command doesn't appear in the command menu; type it in full. On Linux without a Desktop folder, the files are written to your home directory.

The command also prints a summary in the conversation, showing resident set size, JS heap, array buffers, and unaccounted native memory, plus any leak indicators it detected, such as a high memory growth rate or an unusually high number of open handles. The summary says whether most memory is in the JS heap, which the snapshot captures, or in native memory, which it doesn't.

Do one of two things with the output:

• Report it: open a GitHub issue and attach only the -diagnostics.json file, which carries the statistics behind the printed summary and no conversation content or credentials
• Investigate it yourself: if the summary says most memory is JS heap, open the .heapsnapshot file in Chrome DevTools under Memory → Load and sort by retained size to see what's holding the memory

If the summary says most memory is native, the snapshot can't show it; include the summary's leak indicators in your report instead.

Large tables are cut off in the terminal

A Markdown table with more than 200 rows renders its first 200 rows followed by a … N more rows not shown line. Only the display is capped: the full table stays in the conversation, and /copy copies every row. For a table too large to read in the terminal, ask Claude to write it to a file instead. Before v2.1.208, Claude Code rendered every row, so resuming a session that contained a very large table could stall while it re-rendered.

Auto-compaction stops with a thrashing error

If you see Autocompact is thrashing: the context refilled to the limit..., automatic compaction succeeded but a file or tool output immediately refilled the context window several times in a row. Claude Code stops retrying to avoid wasting API calls on a loop that isn't making progress.

To recover:

1. Ask Claude to read the oversized file in smaller chunks, such as a specific line range or function, instead of the whole file
2. Run /compact with a focus that drops the large output, for example /compact keep only the plan and the diff
3. Move the large-file work to a subagent so it runs in a separate context window
4. Run /clear if the earlier conversation is no longer needed

Command hangs or freezes

If Claude Code seems unresponsive:

1. Press Ctrl+C to attempt to cancel the current operation
2. If unresponsive, you may need to close the terminal and restart

Restarting doesn't lose your conversation. Run claude --resume in the same directory to pick the session back up.

Garbled or corrupted text in an editor's integrated terminal

If characters render as boxes, smears, or the wrong glyphs when running Claude Code in the VS Code, Cursor, or Devin Desktop integrated terminal, the terminal's GPU renderer is likely the cause. Run /terminal-setup inside Claude Code to set terminal.integrated.gpuAcceleration to "off", or set it manually in your editor settings and reload the window. See Terminal configuration for the other settings /terminal-setup writes.

Search and discovery issues

If the Search tool, @file mentions, custom agents, or custom skills aren't finding files, the bundled ripgrep binary may not run on your system. Install your platform's ripgrep package and tell Claude Code to use it instead:

brew install ripgrep

sudo apt install ripgrep

apk add ripgrep

pacman -S ripgrep

winget install BurntSushi.ripgrep.MSVC

Then set USE_BUILTIN_RIPGREP to 0, either in your shell environment or in the env block of your settings.json:

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

To confirm the switch took effect, run claude doctor in your terminal and check that the Search line shows the path of your system ripgrep instead of OK (bundled).

Slow or incomplete search results on WSL

Disk read performance penalties when working across file systems on WSL may result in fewer-than-expected matches when using Claude Code on WSL. Search still functions, but returns fewer results than on a native filesystem.

Solutions:

1. Submit more specific searches: reduce the number of files searched by specifying directories or file types: "Search for JWT validation logic in the auth-service package" or "Find use of md5 hash in JS files".

2. Move project to Linux filesystem: if possible, ensure your project is located on the Linux filesystem (/home/) rather than the Windows filesystem (/mnt/c/).

3. Use native Windows instead: consider running Claude Code natively on Windows instead of through WSL, for better file system performance.

Get more help

If you're experiencing issues not covered here:

1. Run /doctor for a setup checkup and /mcp to check MCP server status
2. Use the /feedback command within Claude Code to report problems directly to Anthropic
3. Check the GitHub repository for known issues
4. Ask Claude directly about its capabilities and features. Claude has built-in access to its documentation.

For account, billing, or subscription problems, contact Anthropic support instead: sign in at claude.ai (Console users: platform.claude.com), click your initials in the lower left, and select Get help. See How to get support for the full flow, including who can reach a human agent on each plan.