claude-code-sandbox/docs/claude-code-docs/Troubleshooting.md

title	source	author	published	created	description	tags
Troubleshooting	https://docs.anthropic.com/en/docs/claude-code/troubleshooting	Anthropic		2025-05-26	Solutions for common issues with Claude Code installation and usage.	clippings

Common installation issues

When installing Claude Code with npm, you may encounter permission errors if your npm global prefix is not user writable (eg. /usr, or /use/local).

The safest approach is to configure npm to use a directory within your home folder:

# First, save a list of your existing global packages for later migration
npm list -g --depth=0 > ~/npm-global-packages.txt

# Create a directory for your global packages
mkdir -p ~/.npm-global

# Configure npm to use the new directory path
npm config set prefix ~/.npm-global

# Note: Replace ~/.bashrc with ~/.zshrc, ~/.profile, or other appropriate file for your shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Apply the new PATH setting
source ~/.bashrc

# Now reinstall Claude Code in the new location
npm install -g @anthropic-ai/claude-code

# Optional: Reinstall your previous global packages in the new location
# Look at ~/npm-global-packages.txt and install packages you want to keep

This solution is recommended because it:

• Avoids modifying system directory permissions
• Creates a clean, dedicated location for your global npm packages
• Follows security best practices

System Recovery: If you have run commands that change ownership and permissions of system files or similar

If you’ve already run a command that changed system directory permissions (such as sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr) and your system is now broken (for example, if you see sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set), you’ll need to perform recovery steps.

Ubuntu/Debian Recovery Method:

1. While rebooting, hold SHIFT to access the GRUB menu
2. Select “Advanced options for Ubuntu/Debian”
3. Choose the recovery mode option
4. Select “Drop to root shell prompt”
5. Remount the filesystem as writable:
6. Fix permissions:
7. Reinstall affected packages (optional but recommended):
8. Reboot:

   reboot
   

Alternative Live USB Recovery Method:

If the recovery mode doesn’t work, you can use a live USB:

1. Boot from a live USB (Ubuntu, Debian, or any Linux distribution)
2. Find your system partition:

   lsblk
   

3. Mount your system partition:
4. If you have a separate boot partition, mount it too:
5. Chroot into your system:
6. Follow steps 6-8 from the Ubuntu/Debian recovery method above

After restoring your system, follow the recommended solution above to set up a user-writable npm prefix.

Auto-updater issues

If Claude Code can’t update automatically, it may be due to permission issues with your npm global prefix directory. Follow the recommended solution above to fix this.

If you prefer to disable the auto-updater instead, you can use:

Permissions and authentication

If you find yourself repeatedly approving the same commands, you can allow specific tools to run without approval:

Authentication issues

If you’re experiencing authentication problems:

1. Run /logout to sign out completely
2. Close Claude Code
3. 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:

1. Use /compact regularly to reduce context size
2. Close and restart Claude Code between major tasks
3. Consider adding large build directories to your .gitignore file

Command hangs or freezes

If Claude Code seems unresponsive:

1. Press Ctrl+C to attempt to cancel the current operation
2. 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:

1. Go to Settings → Tools → Terminal
2. Click the “Configure terminal keybindings” hyperlink next to “Override IDE Shortcuts”
3. 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.

If you’re experiencing issues not covered here:

1. Use the /bug command within Claude Code to report problems directly to Anthropic
2. Check the GitHub repository for known issues
3. Run /doctor to check the health of your Claude Code installation