Text of code.claude.com › docs › en › troubleshooting as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Troubleshooting - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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: Symptom Go to command not found , install fails, PATH issues, EACCES , TLS errors Troubleshoot installation and login Update or install download fails with The connection dropped while downloading the update or aborted Troubleshoot installation and login Update or install fails with Release verification failed for Claude Code Troubleshoot installation and login Session footer shows Auto-update failed · Run claude doctor in red Troubleshoot installation and login Login loops, OAuth errors, 403 Forbidden , “organization disabled”, Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry credentials Troubleshoot installation and login Settings not applying, hooks not firing, MCP servers not loading Debug your configuration Session started in auto mode, or Claude edits files and runs commands without asking Which mode a session starts in After you update Claude Code or the Agent SDK, tool calls are denied in claude -p or SDK runs that don’t pass --permission-mode , permissionMode , or permission_mode Tool calls denied in claude -p and Agent SDK runs API Error: 5xx , 529 Overloaded , 429 , request validation errors Error reference model not found or you may not have access to it Error reference A command Claude runs fails with Disk full: , Disk quota used up: , Nearly out of inodes: , The command was not started: , Your disk quota is full , is full (ENOSPC) , or Command output was lost Error reference VS Code extension not connecting or detecting Claude VS Code integration Claude Code process exited with code 1 in VS Code or an SDK app Error reference JetBrains plugin or IDE not detected JetBrains integration High CPU or memory, slow responses, hangs, search not finding files Performance and stability below 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: 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 Close and restart Claude Code between major tasks Consider adding large build directories to your .gitignore file Restart with claude --safe-mode to check whether a plugin, MCP server, or hook is the source. If usage drops, see Debug your configuration to find which one If a session’s heap memory passes 2.5GB, a critical memory usage warning appears.

To free the memory, restart Claude Code and run claude --continue to resume the conversation in a fresh process. Outside fullscreen rendering , running /compact frees memory too. The warning disappears once memory use drops back below 2.5GB. 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 .

Claude Code hides the command from the command menu ; type it in full. On Linux without a Desktop folder, the files are written to your home directory. The .heapsnapshot file contains every string in the process, including your full conversation and credentials. Don’t attach it to a public issue or share it. The command also prints a summary in the conversation, showing the process’s total memory, how much of it is in the JS heap, and how much sits outside the heap.

The summary also lists any leak indicators, 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. Report the output or investigate it yourself: 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: Ask Claude to read the oversized file in smaller chunks, such as a specific line range or function, instead of the whole file Run /compact with a focus that drops the large output, for example /compact keep only the plan and the diff Move the large-file work to a subagent so it runs in a separate context window Run /clear if the earlier conversation is no longer needed If the error comes back after a /clear , run /context and compare the Messages row with the rows above it: Messages is the largest row : a file or tool output in the new conversation is refilling the window, so work through steps 1 to 3 again The other rows together are larger : what loads at session start leaves too little room to work in, so trim what loads at startup Command hangs or freezes If Claude Code seems unresponsive: Press Ctrl+C to attempt to cancel the current operation 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. Stray >0q at startup or >4m after exit These characters, printed by terminals built on a VTE library older than 0.53, are the ends of two Claude Code control sequences. To stop the text, update Claude Code to v2.1.301 or later, which skips both sequences when it identifies such a terminal. If the text remains, print the VTE version from the terminal’s shell: echo $VTE_VERSION On a VTE-based terminal, a result below 5300 means a library older than 0.53: update or replace the terminal to get VTE 0.53 or later.

Otherwise,

The rest of this page is on the live site.