Dieser Guide hilft dir bei der Diagnose und Lösung häufiger Probleme mit Claude Code. Nutze die /doctor Befehl zur schnellen Diagnose.

Installation Probleme

Fehler: command not found: claude oder 'claude' is not recognized

Die Installation hat erfolgreich abgeschlossen, aber claude funktioniert nicht.

Ursache: Das Installationsverzeichnis ist nicht in deinem PATH.

Lösung:

# macOS/Linux: zeige deinen PATH
echo $PATH | tr ':' '\n' | grep local/bin

# Falls `~/.local/bin` nicht vorhanden ist, füge es hinzu:
# Zsh (macOS Standard)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash (Linux Standard)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verifizieren:
claude --version

Windows PowerShell:

# Prüfe PATH
$env:PATH -split ';' | Select-String 'local\\bin'

# Hinzufügen falls nötig
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# Terminal neu starten und prüfen
claude --version

Fehler: syntax error near unexpected token '<' oder Invoke-Expression: Missing argument in parameter list

Das Installer-Skript hat HTML statt eines Shell-Skripts erhalten.

Ursache: Netzwerkrouting, regionale Blockierung oder temporäre Service-Störung.

Lösungen:

  1. Warte ein paar Minuten und versuche es erneut — das Problem ist oft temporär

  2. Verwende alternative Installationsmethode:

    # macOS/Linux: Homebrew
brew install --cask claude-code

# Windows: WinGet
winget install Anthropic.ClaudeCode

  3. Prüfe Netzwerkkonnektivität:

    curl -sI https://storage.googleapis.com

Fehler: curl: (56) Failure writing output to destination

Die Download-Verbindung ist unterbrochen.

Ursache: Netzwerk-Unterbrechung, blockierter Download oder Speicher-Limit.

Lösungen:

  1. Prüfe Netzwerk-Stabilität:

    curl -fsSL https://storage.googleapis.com -o /dev/null

  2. Verwende alternative Installationsmethode:

    # macOS/Linux
brew install --cask claude-code

# Windows
winget install Anthropic.ClaudeCode

  3. Manueller Download:

    # Download zunächst, dann auführen
curl -fsSL https://claude.ai/install.sh -o install.sh
bash install.sh

Fehler: Killed während Installation auf Low-Memory Linux Server

Der Linux OOM-Killer beendete den Prozess aufgrund unzureichenden Speicherns.

Ursache: Server hat weniger als 4 GB freien RAM.

Lösung — Swap-Space hinzufügen:

# Erstelle 2 GB Swap-Datei
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Versuche Installation erneut
curl -fsSL https://claude.ai/install.sh | bash

Fehler: TLS connect error, SSL/TLS secure channel oder unable to get local issuer certificate

TLS-Handshake-Fehler, oft aufgrund von Corporate Proxies mit TLS-Inspection.

Lösungen:

  1. Update CA-Zertifikate:

    # Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

  2. Windows PowerShell — Enable TLS 1.2:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

  3. Corporate CA-Zertifikat konfigurieren:

    export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
curl -fsSL https://claude.ai/install.sh | bash

    Frage dein IT-Team nach der Zertifikat-Datei.

Fehler: Failed to fetch version from storage.googleapis.com

Installer kann den Download-Server nicht erreichen.

Ursache: storage.googleapis.com ist auf deinem Netzwerk blockiert.

Lösungen:

  1. Proxy konfigurieren (falls vorhanden):

    export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

  2. Alternative Installationsmethode:

    brew install --cask claude-code  # macOS/Linux
winget install Anthropic.ClaudeCode  # Windows

Fehler: Linux: wrong binary variant installed (musl/glibc mismatch)

Error loading shared library libstdc++.so.6: No such file or directory

Ursache: Falscher Binary für dein System heruntergeladen.

Lösung:

# Prüfe welcher libc du hast
ldd /bin/ls | head -1

# Falls auf glibc aber musl-Binary: Neu installieren
curl -fsSL https://claude.ai/install.sh | bash

# Falls auf musl (Alpine Linux)
apk add libgcc libstdc++ ripgrep

Fehler: Illegal instruction auf Linux

Ursache: Binary passt nicht zu deiner CPU-Architektur.

Lösung:

# Prüfe Architektur
uname -m
# x86_64 = 64-bit Intel/AMD
# aarch64 = ARM64

# Falls falsch: Melde Issue mit uname -m Output
# Versuche alternative Installation
brew install --cask claude-code

Fehler: dyld: cannot load auf macOS

dyld: cannot load 'claude-...' ... Abort trap: 6

Ursache: Binary passt nicht zu deiner macOS-Version.

Lösung:

# Prüfe macOS-Version (braucht 13.0+)
# Apple Menu → About This Mac

# Falls älter: macOS aktualisieren

# Alternative: Homebrew
brew install --cask claude-code

Fehler: Windows irm oder && not recognized

Du führst das falsche Installer-Kommando für deine Shell aus.

Falls irm not recognized — du bist in CMD, nicht PowerShell:

# Öffne PowerShell und führe aus
irm https://claude.ai/install.ps1 | iex

Falls && not valid — du bist in PowerShell aber führst CMD-Kommando aus:

# Richtig für PowerShell
irm https://claude.ai/install.ps1 | iex

Fehler: WSL — exec: node: not found

WSL verwendet Windows Node.js statt Linux Node.js.

Lösung:

# Prüfe welches Node verwendet wird
which npm
which node

# Falls Paths mit /mnt/c/ starten → Windows Versionen werden verwendet
# Installiere Linux Node.js via nvm oder Package Manager

# via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.nvm/nvm.sh
nvm install node

# Prüfe wieder
which npm  # sollte /home/... sein, nicht /mnt/c/...

Authentifizierung Probleme

Repeated permission prompts

Du wirst ständig aufgefordert, denselben Befehl zu genehmigen.

Lösung: Verwende /permissions um bestimmte Tools dauerhaft zuzulassen:

/permissions
# Wähle Tool aus und setze dauerhaften Zugriff

Fehler: OAuth error: Invalid code

OAuth error: Invalid code. Please make sure the full code was copied

Ursache: Login-Code ist abgelaufen oder wurde beim Copy-Paste gekürzt.

Lösungen:

  1. Schneller eingeben: Drücke Enter direkt nach dem Browser-Öffnen
  2. Manuelles Copy: Drücke c um URL in Zwischenablage zu kopieren
  3. Remote-Session: Falls SSH: Kopiere URL von Terminal und öffne in lokalem Browser

Fehler: 403 Forbidden nach Login

API Error: 403 {"error":{"type":"forbidden",...}}

Lösungen:

  1. Claude Pro/Max: Prüfe aktives Abo auf claude.ai/settings
  2. Console-Nutzer: Admin muss "Claude Code" oder "Developer" Rolle zuweisen
  3. Behind Proxy: Prüfe Proxy-Konfiguration unter Netzwerk-Probleme

Fehler: "This organization has been disabled" trotz aktiv Abo

Ursache: ANTHROPIC_API_KEY Umgebungsvariable überschreibt dein Abo.

Lösung:

# Entferne die Variable
unset ANTHROPIC_API_KEY

# Prüfe ~/.zshrc, ~/.bashrc, ~/.profile
# und entferne `export ANTHROPIC_API_KEY=...` Zeilen

# Starten und Check
claude
/status  # zeigt Auth-Methode

Fehler: OAuth login fails in WSL2

Browser öffnet sich nicht richtig.

Lösung:

# Setze Browser explizit
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

# Oder: Manuelles Copy
# Drücke 'c' wenn Login-Prompt erscheint

Netzwerk Probleme

Fehler: TLS/SSL bei Installation

Siehe "Installation Probleme" Sektion oben.

Fehler: Proxy blockiert Download

Lösung:

# Setze Proxy-Variablen
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal

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

# Oder: Zertifikat hinzufügen
export NODE_EXTRA_CA_CERTS=/path/to/ca.pem

Fehler: API requests fail mit Corporate Proxy

Lösung: Proxy für Claude Code konfigurieren:

// settings.json
{
  "env": {
    "HTTP_PROXY": "http://proxy.example.com:8080",
    "HTTPS_PROXY": "http://proxy.example.com:8080"
  }
}

Performance Probleme

Hohes CPU/Memory-Auslastung

Lösungen:

  1. Context komprimieren: /compact regelmäßig nutzen
  2. Neu starten: Claude Code zwischen großen Tasks neustarten
  3. gitignore erweitern: Große Build-Directories ausschließen
# In .gitignore hinzufügen
node_modules/
.next/
dist/
build/

Command hängt oder friert ein

Lösung:

  1. Ctrl+C zum Unterbrechen
  2. Falls nicht responsiv: Terminal schließen und neustarten

Suche funktioniert nicht

Suche-Tool, @file Mentions, Custom Agents funktionieren nicht.

Ursache: System ripgrep nicht installiert.

Lösung:

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Fedora
sudo dnf install ripgrep

# Alpine
apk add ripgrep

# Dann in settings.json oder Shell
export USE_BUILTIN_RIPGREP=0

Slow search results auf WSL

WSL cross-filesystem Performance ist langsamer.

Lösungen:

  1. Spezifischere Suchen: "Search for JWT validation in auth package"
  2. Auf Linux-Filesystem verschieben: /home/ statt /mnt/c/
  3. Natives Windows verwenden: Falls möglich

MCP Probleme

MCP Server startet nicht

Diagnose:

/doctor  # zeigt MCP-Probleme

Häufige Ursachen:

  1. Server-Datei nicht gefunden: Prüfe Pfad in .mcp.json
  2. Falsche Permissions: chmod +x für Server-Binary
  3. Fehlende Dependencies: Server hat nicht alle Abhängigkeiten

Lösung:

// .mcp.json — prüfe Pfade
{
  "mcpServers": {
    "myserver": {
      "command": "/absolute/path/to/server",
      "args": ["--option"]
    }
  }
}

Timeout beim MCP Server Verbinden

Ursache: Server antwortet zu langsam oder startet nicht.

Lösung:

# Teste Server manuell
/absolute/path/to/server --option

# Prüfe ob Server läuft
ps aux | grep server

# Starte Claude Code neu
claude

IDE Integration Probleme

JetBrains IDE nicht erkannt auf WSL2

Ursache: WSL2 Netzwerk NAT blockiert Verbindung.

Lösung 1 — Windows Firewall Regel:

# WSL2 IP finden
wsl hostname -I  # z.B. 172.21.123.45

# PowerShell als Admin öffnen

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

Lösung 2 — WSL2 Mirrored Networking:

In ~/.wslconfig (Windows-Verzeichnis):

[wsl2]
networkingMode=mirrored

Dann wsl --shutdown in PowerShell

Escape-Key funktioniert nicht in JetBrains

Lösung:

  1. Gehe zu Settings → Tools → Terminal
  2. Unchecke "Move focus to the editor with Escape" oder lösche den Shortcut

Dokumentation Probleme

Missing language tags in code blocks

Generated Markdown hat keine Code-Block-Sprach-Tags.

Lösung: Claude fragen um Language-Tags zu ergänzen:

"Add appropriate language tags to all code blocks in this markdown file."

Sandbox Probleme

Fehler: Sandbox requires socat and bubblewrap

WSL2 hat fehlende Dependencies.

Lösung:

# Ubuntu/Debian WSL2
sudo apt-get install bubblewrap socat

# Fedora WSL2
sudo dnf install bubblewrap socat

WSL1 unterstützt Sandboxing nicht — upgraden zu WSL2 nötig.

Git Integration Probleme

Git-Befehle funktionieren nicht

Ursache: Git nicht installiert oder nicht im PATH.

Lösung:

# Prüfe Git-Installation
which git
git --version

# Falls nicht vorhanden: Installieren
# macOS
brew install git

# Windows
winget install Git.Git

# Linux
sudo apt install git  # Debian/Ubuntu
sudo dnf install git  # Fedora

Datei-Permissions Fehler

Permission denied beim Schreiben

Ursache: Sandbox blockiert oder keine Schreibberechtigung.

Lösungen:

  1. Prüfe Sandbox-Einstellungen:

    // .claude/settings.json
{
  "sandbox": {
    "enabled": false  // temp. zum Testen
  }
}

  2. Prüfe Dateiberechtigung:

    ls -la filename
# Falls nötig: chmod
chmod u+w filename

  3. Prüfe Verzeichnis-Struktur:

    mkdir -p directory
chmod u+w directory

Allgemeine Diagnose

/doctor Befehl verwenden

# Zu jederzeit in Claude Code
/doctor

Dies prüft:

  • Installation und Version
  • Auto-Update Status
  • Settings-Dateien (JSON-Validierung)
  • MCP-Server-Konfiguration
  • Keybinding-Probleme
  • Context-Auslastung Warnungen
  • Plugin/Agent-Loading Fehler

Logs abrufen

# Debug-Output aktivieren
export CLAUDE_CODE_DEBUG=1
claude

# oder in session
/debug

Manual Troubleshooting

# Konfiguration zurücksetzen
rm ~/.claude.json
rm -rf ~/.claude/
rm -rf .claude/
rm .mcp.json

# Nur Settings zurücksetzen (VORSICHT!)
rm ~/.claude/settings.json

Siehe auch