Troubleshooting
Discover solutions to common issues with Claude Code installation and usage.
Common installation issues
Windows installation issues: errors in WSL
You might encounter the following issues in WSL:
OS/platform detection issues: If you receive an error during installation, WSL may be using Windows npm
. Try:
- Run
npm config set os linux
before installation - Install with
npm install -g @anthropic-ai/claude-code --force --no-os-check
(Do NOT usesudo
)
Node not found errors: If you see exec: node: not found
when running claude
, your WSL environment may be using a Windows installation of Node.js. You can confirm this with which npm
and which node
, which should point to Linux paths starting with /usr/
rather than /mnt/c/
. To fix this, try installing Node via your Linux distribution’s package manager or via nvm
.
nvm version conflicts: If you have nvm installed in both WSL and Windows, you may experience version conflicts when switching Node versions in WSL. This happens because WSL imports the Windows PATH by default, causing Windows nvm/npm to take priority over the WSL installation.
You can identify this issue by:
- Running
which npm
andwhich node
- if they point to Windows paths (starting with/mnt/c/
), Windows versions are being used - Experiencing broken functionality after switching Node versions with nvm in WSL
To resolve this issue, fix your Linux PATH to ensure the Linux node/npm versions take priority:
Primary solution: Ensure nvm is properly loaded in your shell
The most common cause is that nvm isn’t loaded in non-interactive shells. Add the following to your shell configuration file (~/.bashrc
, ~/.zshrc
, etc.):
Or run directly in your current session:
Alternative: Adjust PATH order
If nvm is properly loaded but Windows paths still take priority, you can explicitly prepend your Linux paths to PATH in your shell configuration:
Avoid disabling Windows PATH importing (appendWindowsPath = false
) as this breaks the ability to easily call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.
Linux and Mac installation issues: permission or command not found errors
When installing Claude Code with npm, PATH
problems may prevent access to claude
.
You may also encounter permission errors if your npm global prefix is not user writable (eg. /usr
, or /usr/local
).
Recommended solution: Native Claude Code installation
Claude Code has a native installation that doesn’t depend on npm or Node.js.
The native Claude Code installer is currently in beta.
Use the following command to run the native installer.
macOS, Linux, WSL:
Windows PowerShell:
This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at ~/.local/bin/claude
.
Make sure that you have the installation directory in your system PATH.
Alternative solution: Migrate to local installation
Alternatively, if Claude Code will run, you can migrate to a local installation:
This moves Claude Code to ~/.claude/local/
and sets up an alias in your shell configuration. No sudo
is required for future updates.
After migration, restart your shell, and then verify your installation:
On macOS/Linux/WSL:
On Windows:
Verify installation:
Permissions and authentication
Repeated permission prompts
If you find yourself repeatedly approving the same commands, you can allow specific tools
to run without approval using the /permissions
command. See Permissions docs.
Authentication issues
If you’re experiencing authentication problems:
- Run
/logout
to sign out completely - Close Claude Code
- Restart with
claude
and complete the authentication process again
If problems persist, try:
This removes your stored authentication information and forces a clean login.
Performance and stability
High CPU or memory usage
Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you’re experiencing performance issues:
- Use
/compact
regularly to reduce context size - Close and restart Claude Code between major tasks
- Consider adding large build directories to your
.gitignore
file
Command hangs or freezes
If Claude Code seems unresponsive:
- Press Ctrl+C to attempt to cancel the current operation
- If unresponsive, you may need to close the terminal and restart
ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals
If you’re using Claude Code in JetBrains terminals and the ESC key doesn’t interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains’ default shortcuts.
To fix this issue:
- Go to Settings → Tools → Terminal
- Click the “Configure terminal keybindings” hyperlink next to “Override IDE Shortcuts”
- Within the terminal keybindings, scroll down to “Switch focus to Editor” and delete that shortcut
This will allow the ESC key to properly function for canceling Claude Code operations instead of being captured by PyCharm’s “Switch focus to Editor” action.
Search and discovery issues
If Search tool, @file
mentions, custom agents, and custom slash commands aren’t working, install system ripgrep
:
Then set USE_BUILTIN_RIPGREP=0
in your environment.
Slow or incomplete search results on WSL
Disk read performance penalties when working across file systems on WSL may result in fewer-than-expected matches (but not a complete lack of search functionality) when using Claude Code on WSL.
/doctor
will show Search as OK in this case.
Solutions:
-
Submit more specific searches: Reduce the number of files searched by specifying directories or file types: “Search for JWT validation logic in the auth-service package” or “Find use of md5 hash in JS files”.
-
Move project to Linux filesystem: If possible, ensure your project is located on the Linux filesystem (
/home/
) rather than the Windows filesystem (/mnt/c/
). -
Use native Windows instead: Consider running Claude Code natively on Windows instead of through WSL, for better file system performance.
Markdown formatting issues
Claude Code sometimes generates markdown files with missing language tags on code fences, which can affect syntax highlighting and readability in GitHub, editors, and documentation tools.
Missing language tags in code blocks
If you notice code blocks like this in generated markdown:
Instead of properly tagged blocks like:
Solutions:
-
Ask Claude to add language tags: Simply request “Please add appropriate language tags to all code blocks in this markdown file.”
-
Use post-processing hooks: Set up automatic formatting hooks to detect and add missing language tags. See the markdown formatting hook example for implementation details.
-
Manual verification: After generating markdown files, review them for proper code block formatting and request corrections if needed.
Inconsistent spacing and formatting
If generated markdown has excessive blank lines or inconsistent spacing:
Solutions:
-
Request formatting corrections: Ask Claude to “Fix spacing and formatting issues in this markdown file.”
-
Use formatting tools: Set up hooks to run markdown formatters like
prettier
or custom formatting scripts on generated markdown files. -
Specify formatting preferences: Include formatting requirements in your prompts or project memory files.
Best practices for markdown generation
To minimize formatting issues:
- Be explicit in requests: Ask for “properly formatted markdown with language-tagged code blocks”
- Use project conventions: Document your preferred markdown style in CLAUDE.md
- Set up validation hooks: Use post-processing hooks to automatically verify and fix common formatting issues
Getting more help
If you’re experiencing issues not covered here:
- Use the
/bug
command within Claude Code to report problems directly to Anthropic - Check the GitHub repository for known issues
- Run
/doctor
to check the health of your Claude Code installation - Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation