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

# Troubleshooting

> Diagnose installation problems, interpret error messages, and find help for common issues with Claude Code.

## `claude doctor`

The `doctor` command runs diagnostic checks against your Claude Code installation and reports any problems it finds.

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

The command is enabled by default. Set `DISABLE_DOCTOR_COMMAND=1` to hide it from the CLI.

## Debug mode

Pass `--debug` to any Claude Code command to enable verbose output, including API request/response details, hook execution logs, and internal diagnostics.

```bash theme={null}
claude --debug
claude --debug "explain this file"
```

Debug output includes structured timing information for startup phases (MDM load, plugin hook registration, etc.) and full hook stdout/stderr.

## Log files

| Log type            | Location                                   |
| ------------------- | ------------------------------------------ |
| Debug logs          | `~/.claude/debug/`                         |
| Latest debug log    | `~/.claude/debug/latest`                   |
| Session transcripts | `~/.claude/projects/`                      |
| Error logs          | `~/.claude/errors/` (internal builds only) |

Errors are also kept in an in-memory ring buffer (last 100) for the current session. They are written to debug logs and, on internal builds, to the errors directory.

To stream debug logs while Claude Code is running:

```bash theme={null}
tail -f ~/.claude/debug/latest
```

## Checking the version

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

## Common errors and fixes

<AccordionGroup>
  <Accordion title="Authentication failures">
    **Symptoms:** `401 Unauthorized`, `403 Forbidden`, or messages about an invalid API key.

    **Fixes:**

    * Verify `ANTHROPIC_API_KEY` is set correctly in your environment.
    * If using OAuth, run `claude` and follow the login prompt, or check that your OAuth token has not expired.
    * If using `apiKeyHelper`, confirm the script is executable and outputs a valid key on stdout.
    * On Bedrock or Vertex, check that `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` is set and that your cloud credentials are valid.
    * Run `claude doctor` to verify the authentication configuration.
  </Accordion>

  <Accordion title="Rate limiting">
    **Symptoms:** Messages beginning with phrases like `"You've hit your"`, `"You've used"`, `"You're close to"`, or `"You're out of extra usage"`.

    **Fixes:**

    * Wait for the reset time shown in the message.
    * If you are on a usage-based plan, consider upgrading or purchasing extra usage.
    * For team deployments, check whether organization-level policy limits are restricting access (see the [enterprise docs](/advanced/enterprise)).
    * Claude.ai Team and Enterprise subscribers can contact support if limits are unexpectedly low.
  </Accordion>

  <Accordion title="Context window exceeded">
    **Symptoms:** Errors about the context being too long, or Claude stops mid-task with a context-related message.

    **Fixes:**

    * Use `/compact` or `/clear` to start a fresh context.
    * Break large tasks into smaller sub-tasks so each fits within the context window.
    * Consider using the `Explore` built-in agent for read-only investigation—it runs in its own context and returns a summary.
    * Reduce the number of files loaded via `@` mentions or CLAUDE.md auto-inclusions.
  </Accordion>

  <Accordion title="Network and proxy issues">
    **Symptoms:** Timeouts, `ECONNREFUSED`, SSL certificate errors, or `ERR_NETWORK`.

    **Fixes:**

    * Set `HTTPS_PROXY` if outbound traffic must go through a corporate proxy.
    * If you receive SSL certificate errors, ensure the proxy CA certificate is trusted by the system. In CCR environments, the CA is merged automatically.
    * Set `CLAUDE_CODE_CLIENT_CERT` to a PEM client certificate if your proxy requires mutual TLS.
    * Check that `anthropic.com` is reachable from your network; some firewalls block it.
    * Run `claude --debug` and inspect the request/response log for detailed network diagnostics.
  </Accordion>

  <Accordion title="Node.js version incompatibility">
    **Symptoms:** Syntax errors on startup, `require is not defined`, or errors about unsupported ES features.

    **Fixes:**

    * Claude Code requires a recent Node.js version. Run `node --version` and compare against the minimum version in the release notes.
    * Use a version manager (nvm, fnm, Volta) to switch to a supported version.
    * If Claude Code ships as a self-contained binary, ensure you are running the binary and not an older globally installed version (`which claude`).
  </Accordion>

  <Accordion title="Hook failures">
    **Symptoms:** Hooks show errors in the spinner, operations are unexpectedly blocked, or hooks do not appear to run.

    **Fixes:**

    * Run `claude --debug` to see full hook stdout/stderr.
    * Check the hook configuration with `/hooks`.
    * A hook command that exits with code `2` blocks the operation and surfaces stderr to Claude—inspect that output for the block reason.
    * If `allowManagedHooksOnly` is set in managed settings, user/project/local hooks are silently disabled. Contact your administrator.
    * Verify the hook command is executable and the path is correct.
  </Accordion>
</AccordionGroup>

## Performance tips

<Steps>
  <Step title="Use bare mode">
    Pass `--bare` to skip all hooks and reduce startup overhead. Bare mode is useful for scripting and non-interactive use.

    ```bash theme={null}
    claude --bare -p "summarize this file"
    ```
  </Step>

  <Step title="Disable background tasks">
    If background agent tasks cause unexpected CPU usage, set:

    ```bash theme={null}
    export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
    ```
  </Step>

  <Step title="Reduce hook complexity">
    Hooks that run on every `PreToolUse` event add latency to every tool call. Use `matcher` and `if` conditions to narrow hook execution to only the events that need them.
  </Step>
</Steps>

## Submitting feedback

The `/feedback` command (also aliased as `/bug`) opens a feedback form in your browser to report bugs or suggestions.

```
/feedback
/bug
```

The command is not available on Bedrock, Vertex, or Foundry deployments, or when `DISABLE_FEEDBACK_COMMAND=1` / `DISABLE_BUG_COMMAND=1` is set.