Claude Code Deployment Errors: Common Issues & 10-Minute Fix Guide

When developers say "it installed but won't run," they almost always mean the same handful of problems. This guide breaks down the 5 most common Claude Code deployment errors — showing the exact error text, the root cause, and copy-paste commands to fix each one in under 10 minutes.

Common Error Types

<10

Minutes to Fix

Diagnostic Flowchart

Error 1: Invalid or Missing API Key

This is the most common first stumbling block for new users. Claude Code relies on the ANTHROPIC_API_KEY environment variable for authentication — a missing or malformed key triggers an error immediately, though the exact message varies slightly by shell version.

Error messages you'll see:

Terminal output

# Any one of these three means you have an API key problem
Error: ANTHROPIC_API_KEY is not set
AuthenticationError: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Error: Your API key is invalid.

Fix commands:

bash / zsh

# 1. Check if the key is set in current shell
echo $ANTHROPIC_API_KEY

# 2. Set temporarily (current session only)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"

# 3. Persist to shell config (zsh: ~/.zshrc, bash: ~/.bashrc)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# 4. Verify — key must start with sk-ant-api
claude --version   # no auth error = success

Where to get your API key

Your API key is generated at console.anthropic.com → API Keys. Note: the key is shown only once at creation time — copy it immediately. If lost, generate a new one.

Error 2: Node.js Version Incompatible

Claude Code requires Node.js ≥ 18. An older version throws syntax errors at install or startup time — often pointing to internal files, making the root cause hard to spot at first glance.

Error messages you'll see:

Terminal output

SyntaxError: Unexpected token '?'
engine "node" is incompatible with this module. Expected version ">=18". Got "16.x.x"
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

Fix commands:

bash / zsh

# 1. Check current Node version
node -v

# 2a. Switch via nvm (recommended: isolates versions, no system impact)
nvm install 22
nvm use 22
nvm alias default 22

# 2b. Upgrade via Homebrew on macOS (if not using nvm)
brew install node@22
brew link --overwrite node@22

# 3. Reinstall Claude Code after upgrading Node
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Linux server pitfall

Many Ubuntu/Debian systems ship Node.js v12 or v16 in the default apt repository. Use NodeSource or nvm instead of apt install nodejs to avoid getting an outdated version.

Error 3: Permission Denied

Permission errors come in two flavors: npm global install permissions being insufficient, and Claude Code's runtime tool execution being blocked by system or user policy.

Error messages you'll see:

Terminal output

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Error: Permission denied (tool: bash)
EPERM: operation not permitted, unlink

Fix for npm install permissions:

bash / zsh (recommended: change npm prefix, no sudo needed)

# Change global package dir to user home — no sudo needed
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH (update your shell config, then source it)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Reinstall
npm install -g @anthropic-ai/claude-code

Fix for tool permissions (bash/filesystem blocked by Claude Code policy):

bash / zsh

# Explicitly allow tools when launching
claude --allowedTools "bash,read,write,edit"

# Or configure in CLAUDE.md for the project (persistent):
# allowed_tools: ["bash", "read", "write", "edit", "glob", "grep"]

# For CI servers, skip interactive prompts with --dangerously-skip-permissions
# ONLY use in trusted environments, never on production servers
claude --dangerously-skip-permissions -p "your prompt here"

Error 4: Network Timeout or Proxy Issues

Claude Code must reach api.anthropic.com. In restricted network environments — corporate intranets, proxies, or certain cloud regions — you'll see connection timeouts or TLS handshake failures.

Error messages you'll see:

Terminal output

FetchError: request to https://api.anthropic.com/v1/messages failed, reason: connect ETIMEDOUT
Error: Network request failed: ENOTFOUND api.anthropic.com
ProxyError: tunneling socket could not be established, cause=connect ECONNREFUSED

Fix commands:

bash / zsh

# 1. Test direct connectivity
curl -v https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-opus-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 2. Configure HTTP proxy (standard env vars)
export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,internal.company.com"

# 3. Proxy with authentication
export HTTPS_PROXY="http://username:password@proxy.company.com:8080"

# 4. Custom base URL (enterprise internal gateway)
export ANTHROPIC_BASE_URL="https://your-internal-gateway.company.com"

macOS system proxy caveat

macOS System Preferences proxy settings are NOT automatically inherited by Node.js processes. You must explicitly set HTTPS_PROXY in the shell session where you launch Claude Code, or add it permanently to ~/.zshrc.

Error 5: Out of Memory (OOM) Crash

When processing large codebases or long conversations, Claude Code can exhaust the Node.js heap. This error is most common on machines with 8 GB RAM or in memory-constrained CI containers.

Error messages you'll see:

Terminal output

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
Killed (signal 9)   ← Linux OOM Killer terminates the process
RangeError: Maximum call stack size exceeded

Fix commands:

bash / zsh

# 1. Increase Node.js heap limit (MB, adjust to your machine's RAM)
export NODE_OPTIONS="--max-old-space-size=4096"   # 4 GB
claude

# 2. Check current memory usage
free -h          # Linux
vm_stat          # macOS

# 3. For large codebases, create .claudeignore to exclude unnecessary dirs
# (same syntax as .gitignore):
# node_modules/
# dist/
# .next/
# *.lock

# 4. Use /clear in long conversations to reduce context memory pressure

Machine RAM	Suggested `--max-old-space-size`	Notes
8 GB	2048	~6 GB left for OS and other processes
16 GB	4096	Suitable for mid-size codebases
24 GB (M4 Mac mini standard)	8192	Can handle large monorepos
32 GB+	16384	Enterprise projects / parallel instances

Diagnostic Flowchart: 10-Minute Path to Root Cause

Run claude / npm install -gor any Claude Code command

error appears

Read the error keywordapi-key / Node / EACCES / timeout / OOM

match to section

Apply the matching fixcopy the command block from this guide

verify

claude --version succeedsno error = done

Quick keyword reference

api-key / 401 → Error 1
SyntaxError / ESM → Error 2
EACCES / permission → Error 3
ETIMEDOUT / ENOTFOUND → Error 4
heap out of memory / Killed → Error 5

Still stuck? Check these

Node version ≥ 18 (node -v)
Key starts with sk-ant-api
curl can reach api.anthropic.com
Did NOT use sudo npm install -g

Match the error keyword to one of the 5 sections above — most issues resolve in 3 steps.

Bonus: Make Claude Code More Stable on a Server

When running Claude Code long-term on a CI server or cloud host, a few extra details make a real difference beyond fixing the 5 errors above:

Use tmux or screen — keeps the process alive after SSH disconnects, preventing long tasks from being cut short
Write a CLAUDE.md — document project conventions, forbidden paths, and API docs locations to reduce token usage from repeated clarification
Use --output-format json with -p (non-interactive mode) for easier automation parsing
Manage env vars with direnv — auto-loads .env when you cd into the project, no manual export needed

Dedicated macOS server eliminates most errors

Sufficient memory (16–24 GB unified), direct network, no proxy to work around — these are the root reasons why most Claude Code OOM and timeout errors disappear on a proper server. ZavCloud's Mac mini M4 dedicated instances come with Node.js pre-installed; deploy immediately on arrival.

ZavCloud Cloud Mac

Run Claude Code on a Dedicated macOS Server

Mac mini M4 dedicated instance: 24 GB unified memory, 1 Gbps direct uplink, real macOS — say goodbye to OOM and network timeouts.

View Cloud Mac Plans