Skip to main content

​
Run diagnostics first

Before investigating a specific issue, run /doctor inside Claude Code. The doctor screen checks your environment automatically and reports problems with authentication, Node version compatibility, network connectivity, and configuration files.
If /doctor reports a problem, follow the suggested fix before continuing.

​
Common issues

Symptoms: The claude command fails immediately, shows an error on launch, or the terminal hangs.Steps to resolve:
1

Check your Node version

Claude Code requires Node.js 18 or later. Run the following to check:
If your version is below 18, install a current LTS release from nodejs.org or use a version manager such as nvm or fnm.
2

Verify the binary is on your PATH

If this returns nothing, reinstall Claude Code or add the npm global bin directory to your PATH:
3

Run /doctor

If Claude Code starts but exits immediately, try launching with reduced features:
This opens the diagnostic screen without entering a full session.
Symptoms: Claude Code shows an authentication error, says your API key is invalid, or immediately asks you to log in again.Steps to resolve:
1

Re-run the login flow

Inside Claude Code, run:
Follow the prompts to authenticate with your Anthropic account or enter a new API key.
2

Check your API key directly

If you are using an API key rather than OAuth, verify it is valid by testing it with a direct API call:
A 200 response confirms the key is valid.
3

Check for environment variable conflicts

An ANTHROPIC_API_KEY environment variable in your shell overrides stored credentials. Run echo $ANTHROPIC_API_KEY to see if one is set. Unset it or update it to the correct value.
Symptoms: Claude Code says it cannot read or write a file, or a tool is blocked by a permission rule.Steps to resolve:
1

Check file system permissions

The file or directory may not be readable or writable by your user. Run:
Fix ownership or permissions as needed with chmod or chown.
2

Review Claude Code permission rules

Claude Code has its own permission layer on top of the OS. Run /permissions to see active allow and deny rules. A deny rule for the path you are working in will block file access even if the OS allows it.
3

Check for sudo requirements

Some directories (e.g., /etc, /usr) require elevated privileges. Claude Code does not run as root. Move your project to a directory your user owns, or adjust the directory permissions.
Symptoms: Claude stops replying mid-conversation, the spinner runs indefinitely, or responses are very slow.Steps to resolve:
1

Check your internet connection

Claude Code requires a stable internet connection to reach the Anthropic API. Verify basic connectivity:
2

Check Anthropic API status

Visit status.anthropic.com to check for active incidents or degraded performance on the API.
3

Interrupt and retry

Press Ctrl+C to interrupt the current request and try again. If Claude is stuck mid-tool-call, this will abort the operation and return you to the prompt.
4

Restart the session

Run /clear to reset the conversation, or exit with /exit and relaunch. This clears any stale state that may be blocking responses.
Symptoms: A tool from an MCP server is missing, /mcp shows the server as disconnected, or Claude reports it cannot find a specific MCP tool.Steps to resolve:
1

Verify the server process is running

MCP servers are external processes that Claude Code connects to. Check that the server is actually running in another terminal or as a background service.
2

Check your MCP configuration

Run /mcp to review the configured servers. Confirm the transport type, command, and arguments match what the server expects. Common issues include incorrect paths, missing environment variables, or wrong port numbers.
3

Restart Claude Code

MCP connections are established at startup. After correcting the configuration, exit with /exit and relaunch for the changes to take effect.
4

Check the server logs

Most MCP servers write their own logs. Inspect them for connection errors or startup failures that may explain why Claude Code cannot reach the server.
Symptoms: Claude warns that the context is full, responses become less coherent, or you see an error about exceeding the maximum context length.Steps to resolve:
1

Run /compact

The fastest fix is to compress your conversation history:
This summarizes earlier messages into a concise summary, freeing up context space while preserving the important parts of what you have discussed.
2

Start a new session

For very long sessions, run /clear to start fresh. If you have important context you want to carry forward, describe it briefly in the first message of the new session.
3

Switch to a model with a larger context window

Run /model to switch to a model that supports a larger context window. Claude Opus and Claude Sonnet models support up to 200K tokens.
Run /context to visualize how much of your context window is in use before you hit the limit. Running /compact proactively keeps sessions running smoothly.
Symptoms: Responses feel slower or less capable than expected, or you see a different model name than you expected in the status bar.Steps to resolve:Run /model to see the currently active model and switch to a different one:
Select the model you want from the list. Your choice persists for the rest of the session. To set a default model, use /config.
Symptoms: Your API bill is higher than expected.Steps to resolve:
1

Check your current session cost

Run /cost to see a breakdown of token usage and estimated cost for the current session.
2

Use /compact to reduce token usage

Long conversations accumulate history that is re-sent with every request. Run /compact regularly to summarize and shrink the conversation. This is the single most effective way to reduce costs during a long session.
3

Switch to a faster, cheaper model

Run /model and select a smaller model (e.g., Claude Haiku) for tasks that do not require high capability. Reserve larger models for complex reasoning tasks.
4

Monitor usage over time

Run /usage to see aggregate usage across recent sessions. This helps you identify which types of tasks consume the most tokens.
Symptoms: The Claude Code panel does not appear in your editor, or changes made in the terminal are not reflected in the IDE.Steps to resolve:
1

Install the IDE extension

Claude Code integrates with VS Code and JetBrains IDEs via an extension. Install it from the marketplace:
  • VS Code: Search for “Claude Code” in the Extensions panel
  • JetBrains: Search for “Claude Code” in the Plugins marketplace
2

Use /desktop to hand off to the desktop app

If you are running Claude Code in the terminal and want to use the IDE integration, run:
This hands off your current session to the desktop application, which manages the IDE bridge.
3

Restart both the IDE and Claude Code

The IDE bridge connects at startup. Restarting both the IDE extension and the Claude Code terminal session re-establishes the connection.

​
Log files

Claude Code writes diagnostic logs you can inspect when the above steps do not resolve a problem. Log files are stored in your Claude configuration directory:
Each session creates a timestamped log file. Look for ERROR lines to identify what went wrong.

​
Getting help

Submit feedback

Run /feedback inside Claude Code to open the feedback form. Include steps to reproduce the issue and the relevant log output.

GitHub issues

Search existing issues or open a new one on the Claude Code GitHub repository. Include your OS, Node version, and the output of /doctor.