How to Fix Permission Errors and Installation Issues in Claude Code

Permission errors are one of the most common issues when installing or using Claude Code. This guide covers how to diagnose and fix these problems across all major platforms.

Using claude doctor for Diagnostics

Before troubleshooting manually, run the built-in diagnostic tool:

claude doctor

This command checks:

• Installation type (native vs npm)
• PATH configuration
• Authentication status
• System permissions
• File access capabilities

The output highlights specific issues and often suggests fixes. Always start here when debugging problems.

Installation Permission Errors

EACCES Permission Denied (npm installations)

If you see errors like EACCES: permission denied during npm installation, do not use sudo. Instead, use one of these solutions:

Solution 1: Use the Native Installer (Recommended)

The native installer avoids npm permission issues entirely:

# macOS/Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

Solution 2: Fix npm Global Directory Permissions

If you must use npm, configure it to use a user-owned directory:

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

# Configure npm to use it
npm config set prefix '~/.npm-global'

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH=~/.npm-global/bin:$PATH

# Reload your shell
source ~/.bashrc  # or source ~/.zshrc

# Now install Claude Code
npm install -g @anthropic-ai/claude-code

Solution 3: Use nvm (Node Version Manager)

nvm manages Node.js in your home directory, avoiding permission issues:

# Install nvm (see nvm docs for latest)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use a Node version
nvm install --lts
nvm use --lts

# Install Claude Code (no sudo needed)
npm install -g @anthropic-ai/claude-code

PATH Issues

"command not found: claude"

After installation, if your terminal cannot find the claude command:

Step 1: Close and Reopen Terminal

The installer modifies your PATH, but changes only apply to new terminal sessions.

Step 2: Verify Installation Location

Check where Claude was installed:

# macOS/Linux native install
ls -la ~/.local/bin/claude

# Check if in PATH
echo $PATH | tr ':' '\n' | grep -E "(local|npm)"

Step 3: Manually Add to PATH

If the binary exists but is not in PATH, add it manually:

# For native installer on macOS/Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For Homebrew on macOS
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows PATH Issues

On Windows, the native installer adds Claude to your user PATH automatically. If the command is still not found:

1. Restart your terminal (PowerShell or CMD)
2. Check user PATH:
   • Open Settings > System > About > Advanced system settings
   • Click "Environment Variables"
   • Verify the Claude installation path is in your user PATH
3. Try a new terminal window rather than an existing one

Authentication Failures

OAuth Browser Issues

Claude Code authenticates via browser. If authentication fails:

Clear Cached Credentials

claude logout
claude login

Check Browser Availability

Ensure your default browser can open. On headless systems or WSL, you may need to configure a browser:

# WSL: Open browser on Windows host
export BROWSER="explorer.exe"

Verify Subscription Status

Visit claude.ai and confirm your Pro or Max subscription is active. API-only accounts need billing enabled with sufficient credits.

Proxy and Network Issues

If you are behind a corporate proxy:

# Set proxy environment variables
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Then authenticate
claude login

Sandbox Permission Problems

Claude Code uses sandboxing to safely execute commands. Sandbox issues are platform-specific.

macOS Sandbox Permissions

If Claude cannot access certain directories:

1. Grant Full Disk Access: System Settings > Privacy & Security > Full Disk Access > Add your terminal app
2. Check folder permissions: Ensure your user owns the project directory

Windows Sandboxing (WSL)

Native Windows does not support sandboxing. For sandboxed execution, use WSL 2:

# Inside WSL 2
curl -fsSL https://claude.ai/install.sh | bash

Note: WSL 1 does not support sandboxing. Only WSL 2 provides this capability.

Linux Sandbox Issues

On Linux, sandboxing requires certain capabilities. If sandbox operations fail:

# Check if you're in a container or restricted environment
cat /proc/1/cgroup

# Some container environments may not support sandboxing
# In these cases, consider running without sandbox (less secure)

File System Permission Issues

When Claude cannot read or write files in your project:

Check Directory Ownership

# View ownership
ls -la /path/to/project

# Fix ownership (replace 'youruser' with your username)
sudo chown -R youruser:youruser /path/to/project

Verify File Permissions

# Make files readable/writable
chmod -R u+rw /path/to/project

# For directories, ensure execute permission for traversal
find /path/to/project -type d -exec chmod u+x {} \;

Configuring Default Permissions

To reduce permission prompts, configure defaults in your settings:

# View current settings location
claude config path

# Edit settings.json to configure allowed directories

You can also use the --dangerously-skip-permissions flag for one-off operations, though this is not recommended for regular use as it bypasses security checks.

Platform-Specific Troubleshooting

macOS

• Gatekeeper blocks execution: Right-click the installer and select "Open" to bypass Gatekeeper, or run xattr -d com.apple.quarantine /path/to/installer
• Homebrew issues: Run brew doctor to diagnose Homebrew problems before installing Claude Code via Homebrew

Windows (Native)

• PowerShell execution policy: If scripts are blocked, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned in PowerShell as Administrator
• Antivirus interference: Temporarily disable real-time scanning if installation repeatedly fails
• Long path issues: Enable long paths via Group Policy or registry if you work with deeply nested directories

Windows (WSL)

• WSL version: Run wsl -l -v to verify you are using WSL 2 (required for sandboxing)
• Mounting Windows drives: Files on /mnt/c/ may have permission issues. Work within the Linux filesystem (~/) when possible

Linux

• SELinux/AppArmor: Security modules may block Claude operations. Check dmesg or /var/log/audit/audit.log for denials
• Snap/Flatpak terminals: Sandboxed terminal apps may have limited access. Use a native terminal instead

Still Having Issues?

If you have tried the above solutions without success:

1. Run diagnostics: claude doctor provides detailed system information
2. Check GitHub Issues: Search the Claude Code repository for similar problems
3. Collect logs: Error messages and claude doctor output help when seeking support
4. Try reinstalling: A fresh installation often resolves corrupted state

# Complete reinstall (native)
claude uninstall
curl -fsSL https://claude.ai/install.sh | bash

Next Steps

• Learn how to install Claude Code CLI if you have not already
• Configure permissions and sandboxing for your workflow
• Set up MCP servers to extend Claude Code capabilities