Claude Code Won't Start? Setup Troubleshooting FAQ

Getting started with Claude Code? If you're seeing "command not found," "API key not recognized," or other setup errors, this guide covers the most common issues beginners face and how to fix them.

Q1: I'm getting permission denied errors with npm install

Root Causes

Insufficient permissions to write to node_modules, incorrect npm global package directory configuration, or sudo-related permission issues.

Solutions

Method 1: Fix permissions without sudo (Recommended)

# Check current npm prefix
npm config get prefix
# Output example: /usr/local
 
# Create a local npm directory and reconfigure
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
 
# Add to PATH (see Q3 for complete PATH setup)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
 
# Try npm install again
npm install

Method 2: Change directory ownership (if Node.js is in /usr/local)

# Change ownership to current user
sudo chown -R $(whoami) /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/bin
 
# Try npm install again
npm install

Method 3: Use sudo (temporary, not recommended)

# Only use if other methods don't work
sudo npm install -g claude-code
 
# This can cause permission issues later!

Method 4: Use Docker to avoid permission issues entirely

docker run -it node:latest /bin/bash
npm install -g claude-code

:::warning Using sudo with npm can create cascading permission problems in future installations. Prefer Method 1 or 2 whenever possible. :::

Q2: API key is not recognized or shows as unset

Root Causes

The ANTHROPIC_API_KEY environment variable is not set, set in the wrong location, or the shell hasn't reloaded the configuration.

Solutions

Step 1: Verify your API key

Log in to Anthropic Console
Go to "API Keys" section
Create a new key or copy an existing one (starts with sk-ant-)

Step 2: Set the environment variable

For Bash:

# Add to ~/.bashrc
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
 
# Verify
echo $ANTHROPIC_API_KEY

For Zsh (macOS default):

# Add to ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc
 
# Verify
echo $ANTHROPIC_API_KEY

For PowerShell (Windows):

# Set permanently
[Environment]::SetEnvironmentVariable(
    "ANTHROPIC_API_KEY",
    "your-key-here",
    [EnvironmentVariableTarget]::User
)
 
# Restart PowerShell and verify
$env:ANTHROPIC_API_KEY

Step 3: Reload your shell

# Restart the shell completely
exec $SHELL
 
# Or open a new terminal tab and verify
echo $ANTHROPIC_API_KEY
# Output should show: sk-ant-XXXXXXXXXXX...

:::warning Never store your API key in these places:

Git repositories (prevent with .gitignore)
Public files
Emails
Shared shell scripts
Code comments :::

Step 4: Use .env for project-specific configuration

# Create .env in your project root
echo 'ANTHROPIC_API_KEY=your-key-here' > .env
 
# Add to .gitignore to prevent accidental commit
echo '.env' >> .gitignore
 
# For Python projects, use python-dotenv
pip install python-dotenv

# Load .env in your Python script
from dotenv import load_dotenv
import os
 
load_dotenv()
api_key = os.getenv('ANTHROPIC_API_KEY')

Q3: "claude" command not found (PATH configuration)

Root Causes

Claude Code is not in your PATH, or your shell hasn't recognized the updated PATH.

Solutions

Step 1: Locate Claude Code installation

# Check global npm installation location
npm list -g claude-code
# Output: /Users/username/.npm-global/lib/node_modules/claude-code
 
# Check local installation
npm list claude-code
# Output: node_modules/claude-code

Step 2: Add to PATH

Method A: Use npm's global bin directory (Recommended)

# Get npm's prefix
npm config get prefix
# Output: ~/.npm-global
 
# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
# Verify
which claude

Method B: Add explicit PATH

# Add to ~/.bashrc or ~/.zshrc
export PATH="/usr/local/lib/node_modules/.bin:$PATH"
 
# Or if using nvm (Node Version Manager)
export PATH="$HOME/.nvm/versions/node/v20.0.0/bin:$PATH"
 
# Apply changes
source ~/.bashrc

Step 3: Restart your shell

# Complete restart
exec $SHELL
 
# Or open a new terminal tab and verify
claude --version

Step 4: For local installations

# If Claude Code is installed locally in your project
npx claude --version
 
# Or use directly
./node_modules/.bin/claude --version

:::tip On Apple Silicon Macs (M1/M2/M3), you may need to use Rosetta 2:

# Check architecture
uname -m
# Output: arm64 (for M1/M2)
 
# Run with Rosetta if needed
arch -x86_64 zsh

:::

Q4: Claude can't connect behind corporate proxy

Root Causes

Corporate firewalls or proxy servers require explicit configuration for outbound connections.

Solutions

Step 1: Get proxy information from IT Ask your IT department for:

Proxy server address (e.g., proxy.company.com:8080)
Username and password (if required)
Protocol (HTTP, HTTPS, SOCKS)

Step 2: Configure npm proxy

# Set HTTP proxy
npm config set proxy http://[user:password@]proxyserver:port
 
# Set HTTPS proxy
npm config set https-proxy http://[user:password@]proxyserver:port
 
# Example:
npm config set proxy http://proxy.company.com:8080
 
# With authentication:
npm config set proxy http://username:password@proxy.company.com:8080

Step 3: Set environment variables

# For Bash/Zsh
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"
 
# For PowerShell (Windows)
$env:HTTP_PROXY = "http://proxy.company.com:8080"
$env:HTTPS_PROXY = "http://proxy.company.com:8080"

Step 4: Test connection through proxy

# Test with curl
curl -x http://proxy.company.com:8080 https://api.anthropic.com
 
# Should connect successfully

Step 5: Configure Claude Code to use proxy

# Set environment variables, then
claude --version
 
# Or explicitly specify proxy in API calls
export ANTHROPIC_PROXY="http://proxy.company.com:8080"

:::warning If proxy authentication is required, it will be stored in .npmrc. Add to .gitignore:

echo '.npmrc' >> .gitignore

:::

Q5: CLAUDE.md file is not being loaded or recognized

Root Causes

File is in wrong location, has incorrect permissions, or invalid format.

Solutions

Step 1: Verify CLAUDE.md location Claude Code looks for CLAUDE.md in the project root:

# Correct location
/your-project/CLAUDE.md
 
# Wrong locations (won't be recognized)
/your-project/docs/CLAUDE.md
/your-project/src/CLAUDE.md
/your-project/.claude/CLAUDE.md

Step 2: Check if file exists

# List the file
ls -la CLAUDE.md
 
# Create if missing
touch CLAUDE.md
 
# Or copy from template
cp /path/to/template/CLAUDE.md ./

Step 3: Verify file permissions

# Check readable permissions
ls -la CLAUDE.md
# Should show: -rw-r--r--
 
# Add read permission if needed
chmod 644 CLAUDE.md

Step 4: Verify file format

# Check encoding
file CLAUDE.md
# Should show: UTF-8 Unicode text
 
# Check file content structure
head -10 CLAUDE.md
# Should start with YAML frontmatter: ---

Step 5: Specify CLAUDE.md explicitly

# Run from project root
cd /your-project
claude
 
# Or specify path
claude --config ./CLAUDE.md
 
# With workspace
claude --config ./CLAUDE.md --workspace ./src

Step 6: Debug by checking what Claude Code sees

# Enable verbose logging
claude --verbose
 
# Or check if file is accessible
cat CLAUDE.md

:::tip A typical CLAUDE.md structure:

---
name: "My Project"
description: "What this project does"
version: "1.0.0"
---
 
# System Instructions
 
You are an AI assistant for this project.
 
## Tech Stack
 
- Runtime: Node.js
- Framework: Express
- Database: PostgreSQL
 
## Rules
 
- Use TypeScript
- Follow ESLint rules

:::

Q6: Sub-agents won't start or can't communicate

Root Causes

Missing sub-agent API key configuration, port conflicts, or incorrect network settings.

Solutions

Step 1: Verify sub-agent configuration

# Check CLAUDE.md for agent settings
grep -i "agent" CLAUDE.md
 
# Set environment variables
export CLAUDE_AGENT_URL="http://localhost:8000"
export CLAUDE_AGENT_TOKEN="your-agent-token"

Step 2: Check for port conflicts

# On macOS/Linux
lsof -i :8000
 
# Or
netstat -tulpn | grep 8000
 
# Use different port if needed
export CLAUDE_AGENT_PORT=8001

Step 3: Start the agent in another terminal

# Start agent process
claude agent start
 
# Or with Docker
docker run -p 8000:8000 claude-agent:latest
 
# Verify it's running
curl http://localhost:8000/health

Step 4: Test agent connectivity

# Send test message to agent
curl -X POST http://localhost:8000/message \
  -H "Authorization: Bearer $CLAUDE_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello agent"}'

Step 5: Check logs for errors

# View Claude Code logs
claude --log-level debug
 
# View agent logs
tail -f ~/.claude/logs/agent.log

:::warning Sub-agent communication should use HTTPS and authentication in production. Never expose agents without proper security. :::

Q7: Git hooks conflict or don't execute properly

Root Causes

Claude Code and git hook managers (like Husky) trying to execute same hooks, or incorrect permissions on hook files.

Solutions

Step 1: Check existing git hooks

# List hook files
ls -la .git/hooks/
 
# View hook contents
cat .git/hooks/pre-commit
 
# Check if Husky is installed
npm list husky

Step 2: Integrate Claude Code with Husky

# Install Husky if needed
npx husky install
 
# Add Claude Code to pre-commit hook
cat >> .husky/pre-commit << 'EOF'
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
 
# Run Claude Code checks
claude lint
 
# Run other checks
npm run lint
npm run test
EOF
 
# Make executable
chmod +x .husky/pre-commit

Step 3: Verify hook permissions

# Check if hooks are executable
ls -la .git/hooks/pre-commit
# Should show: -rwxr-xr-x (note the x flags)
 
# Add execute permission if needed
chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/pre-push

Step 4: Define hooks in CLAUDE.md

# Add to CLAUDE.md
 
## Git Integration
 
```json
{
  "hooks": {
    "pre-commit": ["claude lint", "npm test"],
    "pre-push": ["claude validate"],
    "commit-msg": ["claude-commit-lint"]
  }
}


**Step 5: Control hook execution order**
```bash
# Example .git/hooks/pre-commit
#!/bin/bash

set -e  # Exit on error

echo "Running Claude Code checks..."
claude lint

echo "Running tests..."
npm test

echo "Running Husky hooks..."
husky pre-commit

echo "✓ All checks passed!"
exit 0

Step 6: Skip hooks for debugging (if needed)

# Skip pre-commit hook
git commit --no-verify
 
# Skip pre-push hook
git push --no-verify

:::warning Use --no-verify only for local debugging. Never disable hooks in CI/CD pipelines or production workflows. :::

Setup Troubleshooting Checklist

Work through this checklist if installation fails:

Verify Node.js and npm

node --version  # v18+
npm --version   # v9+

Check npm configuration

npm config list
npm config get prefix
npm config get cache

Verify API key is set
```
echo $ANTHROPIC_API_KEY | head -c 10
```
Test PATH configuration
```
which claude
claude --version
```
Test network connectivity
```
curl -I https://api.anthropic.com
```

Clear cache and reinstall

npm cache clean --force
npm install -g claude-code

Looking back

Most Claude Code setup errors fall into three categories:

Permission Issues (npm, files, directories)
Environment Variables (API key, PATH, proxy settings)
Network Connectivity (proxy, firewall, DNS)

Read error messages carefully—they often include diagnostic hints. Save complete error logs and compare them against this guide. Following these steps should resolve nearly any setup issue.

Good luck with Claude Code!

Claude Code Won't Start? Setup Troubleshooting FAQ

Q1: I'm getting permission denied errors with npm install

Root Causes

Solutions

Q2: API key is not recognized or shows as unset

Root Causes

Solutions

Q3: "claude" command not found (PATH configuration)

Root Causes

Solutions

Q4: Claude can't connect behind corporate proxy

Root Causes

Solutions

Q5: CLAUDE.md file is not being loaded or recognized

Root Causes

Solutions

Q6: Sub-agents won't start or can't communicate

Root Causes

Solutions

Q7: Git hooks conflict or don't execute properly

Root Causes

Solutions

Setup Troubleshooting Checklist

Looking back

Thank You for Reading

Related Articles

Related Articles

⟐ Claude Code2026-04-29
Claude Code Auto-Update Not Working? A Practical Diagnosis Flow When `claude --version` Won't Move
If you ran `npm install -g @anthropic-ai/claude-code` but `claude --version` still reports last week's number, this guide walks you through the three most common root causes — PATH conflicts, stale binaries, and shell-managed Node — with concrete fixes for each.

⟐ Claude Code2026-03-29
Claude Code Won't Start: Complete Diagnostic Checklist
Systematic guide for diagnosing Claude Code startup failures. Covers Node.js, npm, PATH, permissions, and proxy issues with step-by-step troubleshooting.

⟐ Claude Code2026-07-01
My Claude Code Hooks Stopped Firing After an Update — the Hyphenated Matcher Exact-Match Change in v2.1.195
In Claude Code v2.1.195, hook matchers containing a hyphen switched from partial match to exact match, silently disabling an existing PreToolUse hook. Here is how I isolated the cause and how to write matchers that won't break.