Claude Code funktioniert nicht? Die 5 häufigsten Fehler und ihre Lösung

TL;DR: Die häufigsten Claude-Code-Probleme haben einfache Ursachen: falsche Node.js-Version, ungültiger API Key, Rate Limits, "Content Not Found"-Fehler (betrifft 20–30 % der Sessions) oder Kontext-Verlust bei langen Sessions. claude doctor diagnostiziert die meisten davon automatisch. Dieser Artikel zeigt dir für jeden Fehler die exakte Lösung. Noch nie mit Claude Code gearbeitet? Dann starte mit Was ist Claude Code?.

---

Bevor du anfängst: claude doctor

Anthropic liefert ein eingebautes Diagnose-Tool mit. Bevor du einzelne Fehler manuell suchst, starte:

claude doctor

claude doctor prüft automatisch:

• Node.js-Version und PATH-Konfiguration
• API-Key-Gültigkeit
• Netzwerkverbindung zu Anthropic-Servern
• Konfigurationsdateien auf Fehler
• Berechtigungen im Projektverzeichnis

In vielen Fällen reicht dieser eine Befehl, um das Problem zu identifizieren und eine Lösung vorzuschlagen. Falls nicht, lies weiter.

---

Fehler 1: Installation schlägt fehl oder Claude Code startet nicht

Das Problem

Du tippst claude ins Terminal und bekommst command not found. Oder die Installation mit npm install -g @anthropic-ai/claude-code bricht ab.

Die Ursache

Claude Code braucht Node.js 18 oder neuer. Die häufigste Ursache: Eine veraltete Node.js-Version ist installiert, oder Node.js fehlt komplett. Auf macOS kommt ein zweites Problem dazu: PATH-Konflikte zwischen Homebrew, nvm und der System-Installation. Eine Schritt-für-Schritt-Anleitung findest du in unserem Guide Claude Code installieren und einrichten.

Die Lösung

Schritt 1: Node.js-Version prüfen

node --version

Zeigt die Ausgabe v16.x oder älter? Dann liegt hier das Problem.

Schritt 2: Node.js 18+ installieren

Über Homebrew (macOS):

brew install node@22

Oder über nvm (alle Plattformen):

nvm install 22
nvm use 22

Schritt 3: PATH prüfen

which node
which npm

Beide Befehle sollten Pfade ausgeben. Falls nicht, fehlt Node.js im PATH. Für Zsh (macOS Standard):

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Schritt 4: Claude Code installieren

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

Schritt 5: Installation verifizieren

claude --version

---

Fehler 2: API Key ungültig oder abgelaufen

Das Problem

Claude Code startet, aber beim ersten Prompt kommt eine Fehlermeldung: Invalid API key, Authentication failed oder Unauthorized.

Die Ursache

Drei mögliche Gründe:

1. Der API Key wurde falsch kopiert (fehlende Zeichen am Anfang oder Ende)
2. Der Key ist abgelaufen oder wurde widerrufen
3. Du nutzt den Pro/Max Plan und bist nicht korrekt eingeloggt

Die Lösung

Für Pro/Max-Nutzer (Subscription):

claude logout
claude login

Du wirst durch den OAuth-Flow geführt. Browser öffnet sich, du bestätigst, fertig.

Für API-Nutzer:

Prüfe deinen Key in der Anthropic Console unter console.anthropic.com. Dort siehst du:

• Ob der Key aktiv ist
• Ob er zu deiner Organisation gehört
• Ob die Billing-Informationen hinterlegt sind

Dann setze den Key neu:

export ANTHROPIC_API_KEY="sk-ant-..."

Für permanente Konfiguration:

echo 'export ANTHROPIC_API_KEY="sk-ant-dein-key"' >> ~/.zshrc
source ~/.zshrc

Wichtig: Ein API Key funktioniert nur mit hinterlegter Zahlungsmethode. Ohne Kreditkarte in der Anthropic Console gibt es keine API-Zugriffe.

---

Fehler 3: Rate Limit erreicht

Das Problem

Claude Code stoppt mitten in der Arbeit mit einer Meldung wie Rate limit exceeded oder Too many requests. Du kannst keine neuen Prompts senden.

Die Ursache

Anthropic begrenzt die Nutzung pro Zeitfenster. Der Grund: Einzelne Nutzer verbrauchten zehntausende Dollar Compute auf dem $200-Plan. Ohne Limits wäre der Service für alle anderen unbenutzbar.

Rate Limits betreffen weniger als 5 % der Nutzer. Wenn du regelmäßig an das Limit stößt, gehörst du zu den Power-Usern.

Die Lösung

Sofort-Maßnahmen:

1. Warte. Das Limit setzt sich nach einem Zeitfenster zurück (meistens 1–5 Stunden je nach Plan)
2. Wechsle auf ein kleineres Modell: Sonnet statt Opus verbraucht weniger Kapazität
3. Nutze /compact, um den aktuellen Kontext zu komprimieren

Langfristig:

• Upgrade auf Max Plan ($100/Mo oder $200/Mo) für 5x bzw. 20x mehr Kapazität
• Wechsel auf die API mit Pay-per-Token
• Effizientere Prompts: Plan Mode aktivieren (Shift+Tab 2x), bevor Claude Code Code schreibt

Mehr Details dazu im Artikel Claude Code Rate Limit erreicht.

---

Fehler 4: "Content Not Found" – Claude sucht nicht-existierende Dateien

Das Problem

Claude Code behauptet, eine Datei oder Funktion gefunden zu haben, die gar nicht existiert. Er referenziert Code, der nicht da ist. Oder er versucht, eine Datei zu bearbeiten, die er selbst gerade halluziniert hat.

Das ist der häufigste operative Fehler. Er tritt in 20–30 % der Sessions auf.

Die Ursache

Claude Code arbeitet mit einem Sprachmodell. Wenn der Kontext groß wird oder die Aufgabe mehrdeutig ist, füllt das Modell Lücken mit plausiblen, aber falschen Annahmen. Es "halluziniert" Dateinamen, Funktionssignaturen oder Verzeichnisstrukturen.

Die Lösung

Prävention:

1. Plan Mode nutzen (Shift+Tab 2x). Im Plan Mode listet Claude Code erst alle relevanten Dateien auf, bevor er handelt. Du siehst sofort, ob er die richtigen Dateien referenziert.

2. CLAUDE.md pflegen. Eine gute CLAUDE.md enthält die Projektstruktur, wichtige Dateinamen und Konventionen. Claude Code halluziniert weniger, wenn er die korrekte Struktur kennt. Mehr dazu: Claude Code Best Practices.

3. Kontext begrenzen. Je mehr Dateien im Kontext liegen, desto häufiger verwechselt Claude Code Dinge. Arbeite mit fokussierten Aufgaben statt mit "mach alles auf einmal".

Wenn es passiert ist:

# Session zurückrollen
# Esc+Esc drücken oder:
/rewind

Dann die Aufgabe mit klarerer Beschreibung neu formulieren. Nenne explizit die Dateien, die bearbeitet werden sollen:

Bearbeite die Datei src/auth/login.ts. Ändere die Funktion validateToken()
so, dass sie abgelaufene Tokens zurückweist.

Statt:

Fixe die Authentifizierung.

---

Fehler 5: Kontext-Verlust bei langen Sessions

Das Problem

Nach 30–60 Minuten in derselben Session wird Claude Code schlechter. Er vergisst frühere Anweisungen, wiederholt sich oder macht Fehler, die am Anfang der Session nicht passiert wären.

Die Ursache

Claude Code hat ein begrenztes Context Window. Bei Opus 4.5 sind es 200K Token, bei Opus 4.6 1M Token. Klingt viel, aber in einer aktiven Session füllt sich der Kontext schnell: Jede Datei, jeder Befehl, jede Antwort verbraucht Token.

Wenn der Kontext voll wird, komprimiert Claude Code automatisch. Dabei gehen ältere Details verloren. Das Modell "vergisst" frühere Anweisungen nicht absichtlich – sie werden aus dem aktiven Kontext verdrängt.

Die Lösung

Während der Session:

/compact

/compact komprimiert den aktuellen Kontext. Claude Code fasst bisherige Interaktionen zusammen und gibt Token frei. Nutze es proaktiv alle 20–30 Minuten bei intensiven Sessions.

Für einen Neustart:

/clear

/clear leert die Session komplett. Alle bisherigen Interaktionen werden gelöscht. Nutze das, wenn die Session "verdorben" ist und Claude Code sich in Schleifen dreht.

Strategisch:

• Teile große Aufgaben in mehrere Sessions auf
• Nutze /resume, um eine frühere Session fortzusetzen
• Halte wichtige Entscheidungen in der CLAUDE.md fest – die wird bei jeder Session neu geladen
• Nutze Plan Mode, um den Plan als Referenz zu haben, bevor der Kontext voll wird

---

Bonus: Weitere Probleme und schnelle Lösungen

Problem	Lösung
Claude Code ist sehr langsam	Internetverbindung prüfen. Anthropic-Status-Page checken.
Permission-Prompts nerven	/sandbox aktivieren – reduziert Abfragen um 84 %
Claude Code macht immer wieder denselben Fehler	CLAUDE.md aktualisieren, bekannte Fehler dokumentieren
Session nach Absturz weg	claude --resume oder /resume
Claude Code ändert falsche Dateien	Plan Mode (Shift+Tab 2x) nutzen, Dateien explizit nennen

---

Wann du Hilfe brauchst

Die meisten Probleme löst du mit den Schritten oben in unter 5 Minuten. Falls claude doctor nichts findet und die Lösungen hier nicht greifen, gibt es zwei Anlaufstellen:

1. Anthropic Discord – der #claude-code-Channel hat tausende aktive Nutzer
2. GitHub Issues – das offizielle Repository unter anthropics/claude-code

Für Gründer und C-Level, die nicht selbst debuggen wollen: Genau dafür gibt es Clawdify. Wir liefern einen vorkonfigurierten Claude-Agent auf dedizierter Hardware. Kein Setup, kein Troubleshooting, keine Ausfälle.

---

Häufig gestellte Fragen

Wo finde ich die Logs von Claude Code?

Claude Code speichert Logs im Verzeichnis ~/.claude/logs/. Dort findest du detaillierte Informationen zu jeder Session, einschließlich Fehlermeldungen und API-Aufrufe.

Funktioniert Claude Code offline?

Nein. Claude Code benötigt eine Internetverbindung, um mit den Anthropic-Servern zu kommunizieren. Ohne Verbindung kann er keine Prompts verarbeiten.

Warum halluziniert Claude Code Dateinamen?

Das zugrundeliegende Sprachmodell füllt Wissenslücken mit statistisch wahrscheinlichen Antworten. Wenn der Kontext zu groß oder die Aufgabe zu vage ist, "erfindet" es plausible Dateinamen. Plan Mode und explizite Dateinamen in der Aufgabenstellung reduzieren das Problem deutlich.

Was mache ich, wenn claude doctor nichts findet?

Prüfe manuell: Node.js-Version, API Key, Internetverbindung, Festplattenspeicher. Falls alles stimmt, starte eine neue Session mit /clear und teste mit einem einfachen Prompt wie "Hallo".

Kann ich Claude Code zurücksetzen?

Ja. claude config reset setzt die Konfiguration zurück. Für einen kompletten Neustart: Deinstalliere mit npm uninstall -g @anthropic-ai/claude-code und installiere neu. Eine Übersicht aller wichtigen Befehle findest du im Claude Code Befehle Cheatsheet.

Warum ist Claude Code plötzlich langsamer geworden?

Drei mögliche Gründe: Dein Context Window ist fast voll (nutze /compact), die Anthropic-Server sind unter Last (prüfe status.anthropic.com), oder dein Netzwerk ist langsam.

Bekomme ich meine Arbeit zurück, wenn Claude Code abstürzt?

Ja. Claude Code speichert Sessions automatisch. Mit claude --resume oder /resume kannst du die letzte Session fortsetzen. Alle Dateiänderungen, die Claude Code bereits geschrieben hat, bleiben auf deiner Festplatte erhalten.

Hilft ein Upgrade auf Max bei technischen Problemen?

Nein. Max gibt dir mehr Kapazität und höhere Priorität, aber es löst keine technischen Probleme wie Installation, PATH-Fehler oder Content-Not-Found. Nur bei Rate Limits hilft ein Upgrade direkt.