Skip to main content

Troubleshooting

Solutions for the most common issues when running Claude Code on Windows.

Node.js and npm Issues​

"node is not recognized as an internal or external command"​

Cause: Node.js is not in your system PATH.

Fix:

  1. Reinstall Node.js from nodejs.org — choose the LTS version
  2. During installation, make sure "Add to PATH" is checked
  3. Close and reopen your terminal after installation
  4. Verify with: node --version

"npm is not recognized"​

Cause: npm was not installed with Node.js, or PATH is not set.

Fix:

  1. Reinstall Node.js (npm comes bundled with it)
  2. If npm is installed but not found, add it to PATH manually:
    • Search "Environment Variables" in Windows Start menu
    • Edit the Path variable under "User variables"
    • Add: C:\Users\<YourUsername>\AppData\Roaming\npm
  3. Restart your terminal

Wrong Node.js version​

Cause: Claude Code requires Node.js 18 or later.

Fix:

  1. Check your version: node --version
  2. If below v18, download the latest LTS from nodejs.org
  3. Uninstall the old version first via Windows Settings > Apps

Claude Code Installation Issues​

"claude is not recognized"​

Cause: The global npm bin directory is not in your PATH.

Fix:

  1. Find your npm global prefix: npm prefix -g
  2. Add that path (with \bin appended) to your PATH environment variable
  3. Restart your terminal
  4. Verify: claude --version

Installation fails with permission errors​

Cause: npm does not have permission to write to the global directory.

Fix:

  1. Run PowerShell as Administrator (right-click > "Run as Administrator")
  2. Run: npm install -g @anthropic-ai/claude-code
  3. For a non-admin fix, configure npm to use a user-local directory: 
    npm config set prefix "$env:USERPROFILE\.npm-global"
    Then add %USERPROFILE%\.npm-global\bin to your PATH.

PowerShell Issues​

"Execution of scripts is disabled on this system"​

Cause: PowerShell's execution policy blocks scripts.

Fix:

  1. Open PowerShell as Administrator
  2. Run: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. Type Y to confirm
  4. Close and reopen PowerShell

PowerShell version is too old​

Cause: Windows ships with PowerShell 5.1, but some features work better with PowerShell 7+.

Fix:

  1. Install PowerShell 7: winget install Microsoft.PowerShell
  2. Or download from github.com/PowerShell/PowerShell
  3. Launch with pwsh instead of powershell

Authentication Issues​

"Invalid API key"​

Cause: Your API key is incorrect, expired, or not set.

Fix:

  1. Check your API key at console.anthropic.com
  2. Re-run claude and follow the authentication prompts
  3. If using an environment variable, verify it is set correctly: 
    echo $env:ANTHROPIC_API_KEY

"Rate limit exceeded"​

Cause: You have sent too many requests in a short time.

Fix:

  1. Wait a few minutes and try again
  2. Use /compact to reduce the size of your next request
  3. Check your usage at console.anthropic.com

Permission and File Issues​

Claude cannot read/write files​

Cause: The file or directory permissions prevent access.

Fix:

  1. Make sure you are running Claude Code from within your project directory
  2. Check that the files are not read-only: right-click > Properties > uncheck "Read-only"
  3. Avoid running Claude Code in system-protected directories (like C:\Windows\ or C:\Program Files\)

Long file paths cause errors​

Cause: Windows has a 260-character path limit by default.

Fix:

  1. Enable long paths in Windows:
    • Open Registry Editor (regedit)
    • Navigate to: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
    • Set LongPathsEnabled to 1
  2. Or enable via Group Policy: Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths

MCP Server Issues​

MCP server fails to start​

Cause: The server package is not installed or the command is wrong.

Fix:

  1. Verify the package exists: npx <package-name> --help
  2. Check your settings.json for typos in the server configuration
  3. Review MCP logs: Claude Code stores MCP connection logs that can reveal the error

MCP server connects but tools are missing​

Cause: The server started but did not register its tools correctly.

Fix:

  1. Restart Claude Code (exit and re-enter)
  2. Check that the server version supports the tools you expect
  3. Verify the server configuration includes all required arguments

General Tips​

  • Always restart your terminal after changing PATH or environment variables
  • Run claude doctor (if available) to diagnose common configuration issues
  • Check the version: claude --version — make sure you are on the latest version
  • Update Claude Code: npm update -g @anthropic-ai/claude-code
  • Check disk space: Claude Code needs space for temporary files and caches