Claude Code Not Working? Complete Troubleshooting Checklist — From Setup to Connection Issues

Claude Code Not Working? Start Here

Just getting started with Claude Code? If commands don't run, files don't get created, or you see error messages, work through this checklist from top to bottom. You'll probably find your answer.

Step 0: Check Your Environment

Step 0-1: Is Claude Code Installed?

# Check if Claude Code is installed
claude --version
 
# Should return something like:
# Claude 0.4.0

Not installed?

# macOS (Homebrew)
brew install anthropic/claude/claude
 
# or via npm
npm install -g @anthropic-ai/sdk

Step 0-2: Check Node.js Version

# Verify Node.js version
node --version  # Must be v18.0.0 or higher
 
# Check npm too
npm --version   # 8.0.0 or higher

Version too old?

• macOS: brew install node
• Windows: Download from nodejs.org
• Linux: sudo apt update && sudo apt install nodejs

Step 0-3: Check Your Working Directory

# See where you are
pwd
 
# List files
ls -la | head -10

Step 1: Verify Authentication

Claude Code requires an Anthropic account to work.

Step 1-1: Check Login Status

# Check authentication status
claude auth status
 
# Should show:
# ✓ Authenticated as: your-email@example.com
# Token expires: 2026-06-29

Step 1-2: Not Logged In?

# Log in
claude auth login
 
# Your browser opens automatically for Anthropic login.
# Sign in and grant access.
 
# You'll return to the terminal when done.

Step 1-3: Using an API Key

Alternatively, use an environment variable:

# Set API key
export ANTHROPIC_API_KEY="sk-ant-..."
 
# Verify
echo $ANTHROPIC_API_KEY
 
# Claude Code now uses this key automatically

Getting your API key:

1. Go to console.anthropic.com
2. Click "API Keys"
3. Click "Create Key"
4. Copy the key (only shown once)

Step 2: Test Basic Commands

Step 2-1: Try Interactive Mode

# Start interactive mode
claude
 
# You'll see a prompt:
# You>
 
# Type a simple request
# You> Write a Python function that checks if a number is prime

Getting an error?

Error: Failed to authenticate

→ Go back to Step 1.

Error: Network error

→ Check your internet, firewall, and proxy settings.

Step 2-2: Try One-Shot Mode

# Execute a single command
claude -p "Write a Python function that checks for prime numbers"
 
# Result appears in the terminal

Step 3: Test File Creation

Step 3-1: Create a Test Directory

# Create a test folder
mkdir ~/test-claude-code
cd ~/test-claude-code
 
# Ask Claude Code to create a file
claude -p "Create a package.json file. Name the app test-app"

Check if the file was created:

ls -la
 
# Should show:
# -rw-r--r--  1 user  group  125 Mar 29 12:00 package.json

Step 3-2: View the Created File

# Check contents
cat package.json
 
# Should display valid JSON

File wasn't created?

# Check disk space
df -h
 
# Check write permissions
touch test.txt
ls -la test.txt
rm test.txt

Step 4: Check Project Configuration

Step 4-1: Project Structure

Claude Code expects this folder structure:

my-project/
├── package.json (Node.js)
├── requirements.txt (Python)
├── Cargo.toml (Rust)
├── go.mod (Go)
└── src/
    ├── ...

Step 4-2: Validate package.json

# Check JSON syntax
cat package.json | python3 -m json.tool
 
# Should output formatted JSON. Otherwise:
# json.decoder.JSONDecodeError: ...

Example valid package.json:

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A test app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {}
}

Step 4-3: Install Dependencies

# For Node.js projects
npm install
 
# or
yarn install
 
# For Python
pip install -r requirements.txt
 
# Verify
npm list
pip freeze

Step 5: Check Network and Connectivity

Step 5-1: Test Internet Connection

# Basic connectivity
ping google.com
 
# Should return responses

Step 5-2: Test API Connectivity

# Test connection to Anthropic API
curl -I https://api.anthropic.com
 
# Should return HTTP/2 200

Step 5-3: Behind a Proxy?

For corporate networks:

# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY
 
# Set if needed
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"
 
# Try again
claude -p "Test prompt"

Step 6: Common Error Messages and Fixes

Error: "command not found: claude"

Cause: Claude Code not installed or not in PATH

Fix:

# Check installation
which claude
 
# If nothing, install it
npm install -g @anthropic-ai/sdk
 
# or via Homebrew
brew install anthropic/claude/claude

Error: "Failed to authenticate"

Cause: Invalid API key or no authentication

Fix:

# Reset authentication
claude auth logout
claude auth login
 
# or set API key directly
export ANTHROPIC_API_KEY="sk-ant-..."

Error: "Network error"

Cause: Internet issue, firewall, or proxy

Fix:

# Test connection
ping -c 3 api.anthropic.com
 
# Check DNS
nslookup api.anthropic.com
 
# Ensure port 443 (HTTPS) is open in firewall

Error: "Permission denied"

Cause: Insufficient file or directory permissions

Fix:

# Check permissions
ls -la
 
# Add write permission
chmod 755 .
 
# or move to a writable location
cd ~/Projects

Error: "File not found"

Cause: Wrong file path or relative path issue

Fix:

# Check current directory
pwd
 
# List files
ls -la
 
# Use absolute paths
claude -p "Read this file" --file "/full/path/to/file.txt"

Step 7: Gather Debug Information

If nothing works, collect debug info.

Step 7-1: Enable Debug Logging

# Run with debug output
DEBUG=* claude -p "test"
 
# or
DEBUG=claude:* claude -p "test"

Step 7-2: Capture System Info

# Check all versions
echo "=== Node.js ==="
node --version
npm --version
 
echo "=== Claude Code ==="
claude --version
 
echo "=== OS ==="
uname -a
 
echo "=== PATH ==="
echo $PATH
 
echo "=== API Key (first 20 chars) ==="
echo $ANTHROPIC_API_KEY | head -c 20

Step 7-3: Save Logs to a File

# Capture output
claude -p "test" 2>&1 | tee claude-debug.log
 
# View logs
cat claude-debug.log | head -50

Step 8: When MCP, Edit Tools, or Auto Mode Get Stuck

When there's no error message but the work simply won't progress, the cause often lies in the agent's behavior rather than the CLI itself. In my own indie developer workflow, these three silent stalls have tripped me up the most. Isolate each symptom with a command.

MCP Server Won't Connect

If tools don't show up in the list, or you see MCP server failed to connect, start by checking the connection state.

# List registered MCP servers and their connection status
claude mcp list
 
# Inspect a specific server's config (command, args)
claude mcp get <server-name>

When a server shows failed, the launch command's path or arguments in your config usually don't match the real environment. For servers launched via npx, confirm the package is installed and that the path is executable rather than relative.

# Inspect the project-level config directly
cat .mcp.json
 
# Check the MCP definitions in your user-level config
cat ~/.claude.json | grep -A5 mcpServers

If the server starts but its tools still aren't usable, quit Claude Code and restart it so the server is reloaded. For servers that are slow to initialize, extending the first-connection timeout keeps things stable.

# Launch with a longer first-connection timeout (milliseconds)
MCP_TIMEOUT=30000 claude

Authenticated servers (OAuth and the like) can suddenly stop connecting when a token expires. Add re-authentication to your list of things to rule out.

The Edit Tool Reports "String to replace not found"

A file edit can fail with String to replace not found in file and stall there. There are two causes. One is that the file's latest contents weren't read before the edit. The other is that the target string isn't unique.

The reliable fix is to have the file re-read before editing. Then specify the passage you want to replace generously — including the lines before and after — so it appears exactly once in the file.

# Count how many times the target string appears first
grep -c "string to replace" path/to/file.ts

If this returns 2 or more, that string alone isn't unique — add surrounding lines and try again. A mix of spaces and tabs in the indentation, or a stray full-width space, is enough to break the match, so watch for formatting drift when copying.

Auto Mode Hangs on Approval or Loops

While working in Auto Mode, the confirmation dialog can appear repeatedly and block progress. The safety classifier has judged a command as "needs confirmation" and is waiting for approval.

For commands that are safe to allow (running tests, builds, and so on), adding them to the allow list stops the same prompt from recurring.

# Edit permission rules interactively
/permissions

When you can't escape an approval loop, interrupt the run with Esc, then re-issue the instruction with an explicit scope — "you may auto-run only X inside this directory." Broad permissions raise the risk of unintended actions, so grant only what's needed, step by step.

Next Steps

Once Claude Code works, explore these guides:

• "Claude Code CLI Commands — A Complete Guide" — Learn all commands
• "Claude Code Debugging Mastery" — Advanced debugging

Looking back

When Claude Code doesn't work, check in this order:

1. Environment — Node.js/npm versions
2. Authentication — claude auth status
3. Simple test — claude -p "test"
4. Network — Internet, firewall, proxy
5. Logs — Use DEBUG=* for details

Most issues are solved by this checklist.

Get Claude Code running and boost your productivity!