Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VineeTagarwal-code/claude-code/llms.txt

Use this file to discover all available pages before exploring further.

​
Run diagnostics first

The /doctor command runs a comprehensive set of checks on your installation and configuration: 
/doctor
It checks your install method, shell PATH, Node.js version, API connectivity, ripgrep availability, sandbox status, and more. Review its output before digging into individual issues.

​
Authentication issues

Claude Code looks for your API key in this order:
  1. ANTHROPIC_API_KEY environment variable
  2. Keychain / credential store (set via /login)
  3. Project or user settings
Fix: Run /login to re-authenticate, or export the key in your shell:
export ANTHROPIC_API_KEY=sk-ant-...
Verify it’s set:
echo $ANTHROPIC_API_KEY
If the browser-based OAuth flow fails:
  • Make sure you have an active claude.ai or Anthropic Console account
  • Try /logout then /login to restart the flow
  • As a fallback, set ANTHROPIC_API_KEY directly in your shell environment
These indicate the key is present but invalid or expired.
  • Rotate your API key in the Anthropic Console
  • Re-run /login or update the ANTHROPIC_API_KEY env var
  • Check that ANTHROPIC_BASE_URL is not set to an incorrect endpoint

​
Installation problems

Your shell’s PATH may not include the npm global bin directory.Find where npm installs global binaries:
npm bin -g
Add that path to your shell config (~/.bashrc, ~/.zshrc, or ~/.profile):
export PATH="$(npm bin -g):$PATH"
Reload your shell:
source ~/.zshrc  # or ~/.bashrc
Claude Code requires a recent version of Node.js. Check your version:
node --version
If it’s below v18, upgrade Node.js using your package manager or nvm:
nvm install --lts
nvm use --lts
If you see a message about a lock file or in-progress installation, another install may be running. Wait a moment and retry. If the issue persists, remove the lock file manually:
rm ~/.local/share/claude-code/.install-lock 2>/dev/null || true
Then re-run the install command.
Avoid using sudo with npm. Instead, configure npm to use a user-owned directory:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
Then install again without sudo:
npm install -g @anthropic-ai/claude-code

​
Performance issues

  • Check your network connection and API status
  • Large context windows slow down responses — use /compact to summarize the conversation
  • Use /effort to reduce reasoning effort for simple tasks: 
    /effort low
  • Use /fast to switch to a faster model for the current session
Claude Code has a finite context window. When it fills up:
  • Use /compact to compress the conversation history into a summary
  • Start a fresh session with /clear for unrelated tasks
  • Use /add-dir sparingly — avoid adding large directories unnecessarily
  • Use /cost to see token usage for the current session
  • Use /usage for a summary of recent spending
  • Use /effort low for straightforward tasks
  • Avoid repeatedly reading large files — Claude caches file reads within a session

​
IDE integration issues

Run /ide to check the current IDE connection status and attempt reconnection.Make sure the Claude Code extension is installed in your IDE:
  • VS Code: Install “Claude Code” from the Extensions marketplace
  • JetBrains: Install “Claude Code” from the JetBrains Plugin Marketplace
Restart your IDE after installing the extension.
The diff view requires the IDE extension to be connected. If /ide shows no connection:
  1. Open your IDE with the current project
  2. Ensure the Claude Code extension is enabled
  3. Run /ide again inside Claude Code

​
MCP server issues

Check the server configuration in your settings:
/mcp
Common causes:
  • Wrong command path: Ensure the command in your MCP config is a valid executable on your PATH
  • Missing dependencies: The MCP server process may require its own dependencies installed
  • Environment variables: Some MCP servers need env vars (set them in the env config field)
Check the MCP server logs — Claude Code outputs connection errors to the terminal on startup.
After adding a new MCP server, restart Claude Code. MCP connections are initialized on startup.Verify the server is listed and enabled:
/mcp
If it shows as disabled, toggle it on with the interactive menu.

​
Tool permission issues

To permanently allow a tool, respond with “Always allow” when the permission prompt appears. This adds the tool to your allowedTools list in settings.You can also add it manually in your settings file or via /permissions.
If you accidentally denied a tool permanently, reset it via /permissions or edit your settings file to remove the denial rule.

​
Keeping Claude Code up to date

Run the upgrade command inside Claude Code: 
/upgrade
Or update via npm: 
npm update -g @anthropic-ai/claude-code
Check the current version: 
claude --version

​
Enable debug logging

For deep troubleshooting, use the --debug flag when starting Claude Code, or set the DEBUG environment variable: 
claude --debug
# or
DEBUG=1 claude
This writes detailed logs to ~/.claude/logs/, including tool calls, API requests, and internal state. You can also set CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose for even more detailed output.
If you’re still stuck, use /feedback inside Claude Code to send a report directly to the team.

Build docs developers (and LLMs) love

Get started for freeTalk to us