> ## Documentation Index
> Fetch the complete documentation index at: https://cisco-ea52c096.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common Claude Code problems

## 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.

```bash theme={null}
# Start Claude Code and run the diagnostic command
claude
/doctor
```

If `/doctor` reports a problem, follow the suggested fix before continuing.

***

## Common issues

<AccordionGroup>
  <Accordion title="Claude Code won't start">
    **Symptoms:** The `claude` command fails immediately, shows an error on launch, or the terminal hangs.

    **Steps to resolve:**

    <Steps>
      <Step title="Check your Node version">
        Claude Code requires Node.js 18 or later. Run the following to check:

        ```bash theme={null}
        node --version
        ```

        If your version is below 18, install a current LTS release from [nodejs.org](https://nodejs.org) or use a version manager such as `nvm` or `fnm`.
      </Step>

      <Step title="Verify the binary is on your PATH">
        ```bash theme={null}
        which claude
        ```

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

        ```bash theme={null}
        npm install -g @anthropic-ai/claude-code
        ```
      </Step>

      <Step title="Run /doctor">
        If Claude Code starts but exits immediately, try launching with reduced features:

        ```bash theme={null}
        claude /doctor
        ```

        This opens the diagnostic screen without entering a full session.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Authentication failed">
    **Symptoms:** Claude Code shows an authentication error, says your API key is invalid, or immediately asks you to log in again.

    **Steps to resolve:**

    <Steps>
      <Step title="Re-run the login flow">
        Inside Claude Code, run:

        ```
        /login
        ```

        Follow the prompts to authenticate with your Anthropic account or enter a new API key.
      </Step>

      <Step title="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:

        ```bash theme={null}
        curl https://api.anthropic.com/v1/models \
          -H "x-api-key: YOUR_API_KEY" \
          -H "anthropic-version: 2023-06-01"
        ```

        A 200 response confirms the key is valid.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Permission denied errors">
    **Symptoms:** Claude Code says it cannot read or write a file, or a tool is blocked by a permission rule.

    **Steps to resolve:**

    <Steps>
      <Step title="Check file system permissions">
        The file or directory may not be readable or writable by your user. Run:

        ```bash theme={null}
        ls -la /path/to/file
        ```

        Fix ownership or permissions as needed with `chmod` or `chown`.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Claude is not responding">
    **Symptoms:** Claude stops replying mid-conversation, the spinner runs indefinitely, or responses are very slow.

    **Steps to resolve:**

    <Steps>
      <Step title="Check your internet connection">
        Claude Code requires a stable internet connection to reach the Anthropic API. Verify basic connectivity:

        ```bash theme={null}
        curl -I https://api.anthropic.com
        ```
      </Step>

      <Step title="Check Anthropic API status">
        Visit [status.anthropic.com](https://status.anthropic.com) to check for active incidents or degraded performance on the API.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="MCP server not connecting">
    **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:**

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Restart Claude Code">
        MCP connections are established at startup. After correcting the configuration, exit with `/exit` and relaunch for the changes to take effect.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Out of context / token limit reached">
    **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:**

    <Steps>
      <Step title="Run /compact">
        The fastest fix is to compress your conversation history:

        ```
        /compact
        ```

        This summarizes earlier messages into a concise summary, freeing up context space while preserving the important parts of what you have discussed.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="Wrong model being used">
    **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:

    ```
    /model
    ```

    Select the model you want from the list. Your choice persists for the rest of the session. To set a default model, use `/config`.
  </Accordion>

  <Accordion title="High API costs">
    **Symptoms:** Your API bill is higher than expected.

    **Steps to resolve:**

    <Steps>
      <Step title="Check your current session cost">
        Run `/cost` to see a breakdown of token usage and estimated cost for the current session.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="IDE integration not working">
    **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:**

    <Steps>
      <Step title="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
      </Step>

      <Step title="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:

        ```
        /desktop
        ```

        This hands off your current session to the desktop application, which manages the IDE bridge.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## 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:

```bash theme={null}
# macOS / Linux
~/.claude/logs/

# Windows
%APPDATA%\Claude\logs\
```

Each session creates a timestamped log file. Look for `ERROR` lines to identify what went wrong.

***

## Getting help

<CardGroup cols={2}>
  <Card title="Submit feedback" icon="message">
    Run `/feedback` inside Claude Code to open the feedback form. Include steps to reproduce the issue and the relevant log output.
  </Card>

  <Card title="GitHub issues" icon="github" href="https://github.com/anthropics/claude-code">
    Search existing issues or open a new one on the Claude Code GitHub repository. Include your OS, Node version, and the output of `/doctor`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.