ratanon/claude-code

1# Troubleshooting - Anthropic2 3Source: https://docs.anthropic.com/en/docs/claude-code/troubleshooting4Last Updated: 2025-06-24T09:05:41.3084335 6---7 8Anthropic home page English Search... Search... Navigation Build with Claude Troubleshooting Welcome Developer Guide API Guide Claude Code Model Context Protocol (MCP) Resources Release Notes Documentation Developer Discord Support Getting started Overview Set up Quickstart Memory management Common workflows Build with Claude Add Claude Code to your IDE Model Context Protocol (MCP) GitHub Actions Claude Code SDK Troubleshooting Deployment Overview Amazon Bedrock Google Vertex AI Corporate proxy LLM gateway Development containers Administration Identity and Access Management Security Monitoring Costs Reference CLI reference Interactive mode Slash commands Settings Resources Data usage Legal and compliance  Common installation issues  Linux permission issues When installing Claude Code with npm, you may encounter permission errors if your npm global prefix is not user writable (eg. /usr , or /usr/local ).  Recommended solution: Create a user-writable npm prefix The safest approach is to configure npm to use a directory within your home folder: npm list -g --depth = 0 > ~/npm-global-packages.txt mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @anthropic-ai/claude-code 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 youve 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 ), youll need to perform recovery steps. Ubuntu/Debian Recovery Method: While rebooting, hold SHIFT to access the GRUB menu Select Advanced options for Ubuntu/Debian Choose the recovery mode option Select Drop to root shell prompt Remount the filesystem as writable: mount -o remount,rw / Fix permissions: chown -R root:root /usr chmod -R 755 /usr chown -R YOUR_USERNAME:YOUR_USERNAME /usr/local chmod u+s /usr/bin/sudo chmod 4755 /usr/bin/sudo chmod u+s /usr/bin/su chmod u+s /usr/bin/passwd chmod u+s /usr/bin/newgrp chmod u+s /usr/bin/gpasswd chmod u+s /usr/bin/chsh chmod u+s /usr/bin/chfn chown root:root /usr/libexec/sudo/sudoers.so chmod 4755 /usr/libexec/sudo/sudoers.so chown root:root /etc/sudo.conf chmod 644 /etc/sudo.conf Reinstall affected packages (optional but recommended): dpkg --get-selections > /tmp/installed_packages.txt awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y Reboot: reboot Alternative Live USB Recovery Method: If the recovery mode doesnt work, you can use a live USB: Boot from a live USB (Ubuntu, Debian, or any Linux distribution) Find your system partition: lsblk Mount your system partition: sudo mount /dev/sdXY /mnt If you have a separate boot partition, mount it too: sudo mount /dev/sdXZ /mnt/boot Chroot into your system: sudo chroot /mnt sudo arch-chroot /mnt 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 cant 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: If you prefer to disable the auto-updater instead , you can set the DISABLE_AUTOUPDATER environment variable to 1  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 youre 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: rm -rf ~/.config/claude-code/auth.json claude 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 youre 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 youre using Claude Code in JetBrains terminals and the ESC key doesnt 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 PyCharms Switch focus to Editor action.  Getting more help If youre 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 Was this page helpful? Yes No Claude Code SDK Overview On this page Common installation issues Linux permission issues Recommended solution: Create a user-writable npm prefix System Recovery: If you have run commands that change ownership and permissions of system files or similar Auto-updater issues Permissions and authentication Repeated permission prompts Authentication issues Performance and stability High CPU or memory usage Command hangs or freezes ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals Getting more help9 10---11Document ID: en__docs__claude-code__troubleshooting