„Installiert, aber läuft nicht" – das ist das häufigste Feedback von Claude Code Nutzern, und fast jeder Fehler hat dieselbe Handvoll von Ursachen. Dieser Leitfaden zerlegt die 5 häufigsten Deployment-Fehler: zuerst die genaue Fehlermeldung, dann die Ursache, dann kopierbare Befehle zur Behebung – alles in unter 10 Minuten lösbar.
Fehler 1: Ungültiger oder fehlender API-Key
Das ist die häufigste Hürde für Einsteiger. Claude Code verwendet die Umgebungsvariable ANTHROPIC_API_KEY zur Authentifizierung – fehlt der Key oder ist er falsch formatiert, erscheint sofort ein Fehler.
Mögliche Fehlermeldungen:
# Eine dieser drei Meldungen zeigt ein API-Key-Problem an 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-Befehle:
# 1. Prüfen, ob der Key in der aktuellen Shell gesetzt ist echo $ANTHROPIC_API_KEY # 2. Temporär setzen (gilt nur für die aktuelle Sitzung) export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx" # 3. Dauerhaft in die Shell-Konfiguration schreiben (zsh: ~/.zshrc, bash: ~/.bashrc) echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"' >> ~/.zshrc source ~/.zshrc # 4. Format prüfen: muss mit sk-ant-api beginnen claude --version
Wo Sie den API-Key erhalten
API-Keys werden unter console.anthropic.com → API Keys generiert. Wichtig: Der Key wird nur bei der Erstellung einmal angezeigt – sofort kopieren. Bei Verlust muss ein neuer Key erstellt werden.
Fehler 2: Node.js-Version inkompatibel
Claude Code setzt Node.js ≥ 18 voraus. Ältere Versionen führen bei Installation oder Start zu Syntaxfehlern – oft zeigen die Fehlermeldungen interne Dateipfade, was die eigentliche Ursache auf den ersten Blick verschleiert.
Mögliche Fehlermeldungen:
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-Befehle:
# 1. Aktuelle Node-Version prüfen node -v # 2a. Mit nvm wechseln (empfohlen) nvm install 22 nvm use 22 nvm alias default 22 # 2b. Unter macOS mit Homebrew aktualisieren brew install node@22 brew link --overwrite node@22 # 3. Claude Code nach dem Upgrade neu installieren npm uninstall -g @anthropic-ai/claude-code npm install -g @anthropic-ai/claude-code
Häufige Falle auf Linux-Servern
Das Standard-apt-Repository von Ubuntu/Debian enthält oft Node.js v12 oder v16. Verwenden Sie NodeSource oder nvm statt apt install nodejs, um veraltete Versionen zu vermeiden.
Fehler 3: Berechtigung verweigert (Permission Denied)
Berechtigungsfehler treten in zwei Varianten auf: unzureichende Rechte bei der globalen npm-Installation und durch System- oder Nutzerrichtlinien blockierte Tool-Ausführung zur Laufzeit.
Mögliche Fehlermeldungen:
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules' Error: Permission denied (tool: bash) EPERM: operation not permitted, unlink
Fix für npm-Installationsberechtigungen:
# Globales Paketverzeichnis ins Home-Verzeichnis verschieben – kein sudo nötig mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' # Zum PATH hinzufügen (Shell-Konfiguration aktualisieren, dann neu laden) echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc # Neu installieren npm install -g @anthropic-ai/claude-code
Fix für Tool-Berechtigungen (bash/Dateisystem durch Claude Code-Richtlinie blockiert):
# Tools beim Start explizit erlauben claude --allowedTools "bash,read,write,edit" # Oder in CLAUDE.md konfigurieren (projektweite Persistenz) # Für CI-Server: --dangerously-skip-permissions überspringt interaktive Bestätigungen # Nur in vertrauenswürdigen Umgebungen verwenden claude --dangerously-skip-permissions -p "your prompt here"
Fehler 4: Netzwerk-Timeout oder Proxy-Probleme
Claude Code muss api.anthropic.com erreichen können. In eingeschränkten Netzwerkumgebungen – Unternehmens-Intranets, Proxys oder bestimmten Cloud-Regionen – kommt es zu Verbindungs-Timeouts oder TLS-Handshake-Fehlern.
Mögliche Fehlermeldungen:
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-Befehle:
# 1. Direkte Verbindung testen 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. HTTP-Proxy konfigurieren export HTTPS_PROXY="http://proxy.company.com:8080" export HTTP_PROXY="http://proxy.company.com:8080" export NO_PROXY="localhost,127.0.0.1" # 3. Proxy mit Authentifizierung export HTTPS_PROXY="http://username:password@proxy.company.com:8080" # 4. Benutzerdefinierte Base-URL (Unternehmens-Gateway) export ANTHROPIC_BASE_URL="https://your-internal-gateway.company.com"
macOS-Systemproxy-Hinweis
Die Proxy-Einstellungen in den macOS-Systemeinstellungen werden nicht automatisch von Node.js-Prozessen übernommen. Setzen Sie HTTPS_PROXY explizit in der Shell-Sitzung, in der Sie Claude Code starten, oder schreiben Sie es dauerhaft in ~/.zshrc.
Fehler 5: Speicherüberlauf (OOM) – Prozessabsturz
Bei der Verarbeitung großer Codebasen oder langer Gespräche kann Claude Code den Node.js-Heap erschöpfen. Dieser Fehler tritt am häufigsten auf Maschinen mit 8 GB RAM oder in speicherbeschränkten CI-Containern auf.
Mögliche Fehlermeldungen:
FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory Killed (signal 9) ← Linux OOM-Killer beendet den Prozess RangeError: Maximum call stack size exceeded
Fix-Befehle:
# 1. Node.js-Heap-Limit erhöhen (in MB, je nach verfügbarem RAM) export NODE_OPTIONS="--max-old-space-size=4096" claude # 2. Aktuellen Speicherverbrauch prüfen free -h # Linux vm_stat # macOS # 3. Für große Codebasen: .claudeignore erstellen # node_modules/ # dist/ # .next/ # *.lock # 4. Bei langen Gesprächen: /clear nutzen, um Kontext-Speicher zu reduzieren
| Arbeitsspeicher | Empfohlenes --max-old-space-size |
Hinweis |
|---|---|---|
| 8 GB | 2048 | Ca. 6 GB für OS und andere Prozesse reserviert |
| 16 GB | 4096 | Für mittelgroße Codebasen geeignet |
| 24 GB (M4 Mac mini Standard) | 8192 | Verarbeitet große Monorepos |
| 32 GB+ | 16384 | Unternehmens-Projekte / parallele Instanzen |
Diagnose-Flussdiagramm: 10 Minuten zur Fehlerursache
claude ausführenoder npm install -gclaude --version erfolgreichKein Fehler = FertigSchnelle Stichwort-Referenz
api-key/401→ Fehler 1SyntaxError/ESM→ Fehler 2EACCES/permission→ Fehler 3ETIMEDOUT/ENOTFOUND→ Fehler 4heap out of memory/Killed→ Fehler 5
Noch nicht gelöst? Diese Punkte prüfen
- Node-Version ≥ 18 (
node -v) - Key beginnt mit
sk-ant-api curlerreicht api.anthropic.com- Kein
sudo npm install -gverwendet
Bonus: Claude Code auf einem Server stabil betreiben
Wer Claude Code dauerhaft auf einem CI-Server oder Cloud-Host betreibt, profitiert über die 5 Fehler-Fixes hinaus von einigen weiteren Details:
tmuxoderscreen– Prozess bleibt nach SSH-Trennung aktivCLAUDE.mdpflegen – Projektkonventionen dokumentieren, Token-Verbrauch reduzieren--output-format json– Antworten in Automatisierungsskripten einfacher parsendirenv– Umgebungsvariablen automatisch beim Wechsel ins Projektverzeichnis laden
Ein dedizierter macOS-Server beseitigt die meisten Fehler
Ausreichend Arbeitsspeicher (16–24 GB Unified Memory), direkter Netzwerkzugang, kein Proxy-Umweg – das sind die eigentlichen Gründe, warum OOM- und Timeout-Fehler auf einem richtigen Server verschwinden. ZavClouds dedizierte Mac mini M4-Instanzen kommen mit vorinstallierter Node.js-Umgebung – sofort einsatzbereit.
ZavCloud Cloud Mac
Claude Code auf einem dedizierten macOS-Server betreiben
Mac mini M4 Dedicated Instance: 24 GB Unified Memory, 1 Gbps Direktanbindung, echtes macOS — OOM und Netzwerk-Timeouts gehören der Vergangenheit an.
Cloud-Mac-Angebote ansehen