Inhaltsverzeichnis
- 1. Die „Diagnosebefehle", die man zuerst ausführt
- 2. Authentifizierung und Login
- 3. Nutzung und Rate-Limits (am häufigsten)
- 4. Kontext und Tokens
- 5. Server und Modell
- 6. Installation, PATH und Update
- 7. Netzwerk und Proxy
- 8. MCP (verbundene Server)
- 9. Berechtigungen und Tools
- 10. Sonstiges (thinking / Bild-PDF / IDE)
- 11. Spickzettel: Fehler → Lösung
- Fazit
- FAQ
Du arbeitest in Claude Code, und plötzlich bricht es mit einem Fehler ab — „melde dich neu an", „Rate-Limit", „Prompt ist zu lang", „MCP verbindet sich nicht". Es gibt so viele Arten, dass es mühsam wird, jede einzeln zu googeln. Dieser Artikel ist eine praxisnahe Referenz, die die häufigsten Fehler in Claude Code katalogisiert — jeweils mit Ursache und dem auszuführenden Befehl.
Zuerst das Fazit: Bei den meisten Fehlern grenzt man die Ursache am schnellsten ein, indem man zuerst claude doctor (Volldiagnose), /status (aktuelle Authentifizierung) und /context (Kontext-Aufschlüsselung) ausführt. Und die häufigen Fälle gruppieren sich in vier Familien: ① Nutzung/Rate-Limits, ② Kontext-Überlauf, ③ abgelaufene Authentifizierung, ④ MCP-Verbindungsfehler. Unten ist jede Kategorie als „Symptom → Ursache → Lösungsbefehl" aufgebaut. Setze ein Lesezeichen und springe zum passenden Abschnitt, wenn du feststeckst.
Im Zweifel diese 3 Befehle
— die meisten Fehler beginnen mit dem Eingrenzen der Ursache
Die vier Familien: ① Nutzung/Rate-Limits ② Kontext-Überlauf ③ abgelaufene Authentifizierung ④ MCP-Verbindungsfehler.
Und ganz nebenbei behebt „auf die neueste Version aktualisieren" claude update viele Bugs.
* Die Befehle und Lösungen hier basieren auf der offiziellen Claude-Code-Dokumentation (Stand 2026). Claude Code wird schnell aktualisiert, und Befehlsnamen sowie der Wortlaut von Meldungen können sich ändern. Prüfe den aktuellen Stand mit claude doctor und der offiziellen Doku.
1. Die „Diagnosebefehle", die man zuerst ausführt
Bevor du dich in einzelne Fehler vertiefst: Wenn du die Diagnosebefehle kennst, die beim Eingrenzen der Ursache helfen, kannst du die meisten Probleme schnell festnageln.
| Befehl | Was er zeigt / tut |
|---|---|
claude doctor | Vollständige Prüfung von Installation, Einstellungen, MCP-Servern, Kontextverbrauch |
/status | Die aktuell aktive Authentifizierungsmethode (Pro / Max / Team / API-Key) |
/context | Kontext-Aufschlüsselung (System-Prompt, Verlauf, Dateien, MCP-Tools) |
/usage | Aktuelle Plan-Limits und Reset-Zeiten |
/permissions | Liste der Berechtigungsregeln (allow/deny) und ihrer Quellen |
/mcp | Verbindungsstatus der MCP-Server und Anzahl der bereitgestellten Tools |
/feedback | Einen Bug mit dem Konversationsprotokoll an Anthropic melden |
2. Authentifizierung und Login
Die Familie „es lief und plötzlich werde ich zum Login aufgefordert". Die klassische Falle ist ein API-Key in einer Umgebungsvariablen, der dein Abo überschreibt.
| Symptom | Ursache | Lösung |
|---|---|---|
| Not logged in / Please run /login | Kein gültiger Anmeldedatensatz (abgelaufenes Token o. Ä.) | /login. Wenn es sich wiederholt, Systemuhr und Keychain-Sperre prüfen |
| Invalid API key | Ein veralteter ANTHROPIC_API_KEY bleibt bestehen | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired | Anderswo abgemeldet / vom Admin deaktiviert | /logout → /login. Auch eine Uhrzeitabweichung vermuten |
| This organization has been disabled | API-Key einer deaktivierten Organisation überschreibt | Den Key aus dem Shell-Profil (.zshrc etc.) entfernen → /login → mit /status bestätigen |
| 403 Forbidden (after login) | Abgelaufenes Abo / fehlende Rolle / Proxy-Störung | Abo und Console-Rolle prüfen. Bei Proxys HTTPS_PROXY setzen |
Faustregel: ein API-Key in einer Umgebungsvariablen hat Vorrang vor dem Abo-Login. Wenn du ANTHROPIC_API_KEY für einen CI-Job gesetzt und vergessen hast, wird dein persönlicher Pro/Max-Plan ignoriert. Zuerst mit /status zu prüfen, „welcher Anmeldedatensatz aktiv ist", ist der richtige Schritt.
3. Nutzung und Rate-Limits (am häufigsten)
Die häufigste Beschwerde bei Claude Code. Claude Code verbraucht das 10- bis 100-Fache der Tokens eines Chats (mehrstufige Konversationen, riesige Kontexte, Tool-Roundtrips), daher erreichst du Limits schneller, als es sich anfühlt.
3 Schritte, wenn du „ans Limit stößt"
/usage für Limits und Reset-Zeit, /status für den Anmeldedatensatz/model für ein leichteres Modell, /compact zum Verkleinern des Verlaufs, ungenutztes MCP deaktivieren
Hinweis: „Server is temporarily limiting requests" ist eine kurzlebige serverseitige Drosselung, nicht dein Plan-Limit. Einfach warten und erneut versuchen.
Nicht mit Plan-Limits (pro Sitzung/wöchentlich) verwechseln.
Mehr dazu: „429 / Request rejected" ist eine Rate-Überschreitung bei deinem API-Key oder Workspace. „Credit balance is too low" ist ein aufgebrauchtes Console-Prepaid-Guthaben (im Billing aufladen oder zu einem Abo wechseln). Beachte: Um März 2026 berichteten Max-Nutzer, dass ihre 5-Stunden-Fenster ungewöhnlich schnell leerliefen — in Tech-Medien und in den Issues des offiziellen Repos (vermuteter Bug). Wenn das erneut auftritt, auf die neueste Version aktualisieren, mit /usage messen und bei Bedarf per /feedback melden. Für systematisches Token-Sparen siehe KI-Token-Sparen und Claude-Code-Token-Sparen.
4. Kontext und Tokens
Das taucht auf, wenn du lange Sitzungen oder riesige Dateien bearbeitest.
| Symptom | Ursache | Lösung |
|---|---|---|
| Prompt is too long | Konversation + Dateien überschreiten das Kontextfenster | /compact (zusammenfassen), /clear (zurücksetzen), /context zur Aufschlüsselung, ungenutztes MCP über /mcp deaktivieren |
| Error during compaction: Conversation too long | Nicht genug freier Platz für die Compaction-Ausgabe | Zweimal Esc, um einige Schritte zurückzuspulen, dann /compact. Wenn es weiterhin klemmt, /clear |
| Auto-compact is thrashing | Eine riesige Ausgabe füllt den Kontext direkt nach der Compaction wieder auf | Große Dateien per Zeilenbereich lesen / /compact keep only <focus> / an einen Subagenten auslagern |
Der Trick: niemals eine riesige Datei komplett lesen. Logs und Daten in kleinen Zeilenbereich-Häppchen übergeben. Wenn du das Konzept des Kontextfensters verinnerlichst, wird diese Fehlerklasse deutlich seltener.
5. Server und Modell
| Symptom | Ursache | Lösung |
|---|---|---|
| 500 Internal server error | Vorübergehender Fehler auf Anthropic-Seite | status.claude.com prüfen → nach 1 Min. erneut versuchen |
| 529 Overloaded (repeated) | API vorübergehend an der Kapazitätsgrenze | Ein paar Minuten warten. Mit /model das Modell wechseln, um die Last zu verteilen |
| Request timed out | Keine Antwort innerhalb der 10-Minuten-Voreinstellung | Die Aufgabe aufteilen. Bei langsamer Leitung API_TIMEOUT_MS erhöhen |
| model not found / no access | Falscher Modellname oder nicht in deinem Plan | /model zum Neuauswählen. Veralteten ANTHROPIC_MODEL-Env-Var prüfen |
| Opus is not available with Pro plan | Ausgewähltes Modell nicht in deinem Plan | /model auf ein verfügbares wechseln. Nach einem Plan-Wechsel /logout→/login |
6. Installation, PATH und Update
| Symptom | Ursache | Lösung |
|---|---|---|
| command not found: claude | Installationsverzeichnis nicht im PATH | ~/.local/bin (Win: %USERPROFILE%\.local\bin) zum PATH hinzufügen |
| Install fails (HTML error, etc.) | Proxy / Regionssperre | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | TLS-Inspektion durch Firmen-Proxy / fehlendes CA | NODE_EXTRA_CA_CERTS=/path/ca.pem setzen. NIEMALS NODE_TLS_REJECT_UNAUTHORIZED=0 setzen |
| Multiple claude installations found | npm/Homebrew/native-Duplikate | Eine behalten, z. B. npm uninstall -g @anthropic-ai/claude-code |
| Bugs from an old version | Nicht aktualisiert | claude update (die wirksamste Lösung, die viele Bugs behebt) |
7. Netzwerk und Proxy
Häufig in Firmennetzen und über VPNs. Zuerst die Erreichbarkeit mit curl -I https://api.anthropic.com bestätigen.
| Symptom | Ursache | Lösung |
|---|---|---|
| Unable to connect / ECONNREFUSED / ETIMEDOUT | Offline / VPN-Sperre / Proxy nicht gesetzt | HTTPS_PROXY=http://proxy:8080 setzen. IT bitten, api.anthropic.com freizugeben |
| SSL certificate verification failed (corporate) | Selbstsigniertes Interception-Zertifikat | Das CA-Bundle von der IT holen und NODE_EXTRA_CA_CERTS setzen |
| 403 host_not_allowed (cloud runs) | Außerhalb der Allowlist der Cloud-Umgebung | Netzwerkzugriff auf Custom stellen und die Zieldomain freigeben |
8. MCP (verbundene Server)
Diese treten auf, sobald du MCP-Server einsetzt. Status zuerst mit /mcp prüfen.
| Symptom | Ursache | Lösung |
|---|---|---|
| Server failed to connect / Pending approval | Server abgestürzt / nicht erreichbar / Authentifizierung nötig | /mcp für den Status. stdio: prüfen, ob der Befehl existiert + ausführbar ist; HTTP: URL/Auth-Header prüfen |
| Tool not found | Verbunden, aber keine Tools bereitgestellt / falscher Name | /mcp zur Bestätigung der Tool-Anzahl, claude mcp get <name> für den Zustand |
| Reconnection attempts exhausted | HTTP/SSE-Server nach 5 Versuchen ausgefallen | Bestätigen, dass der Server läuft, manueller Reconnect in /mcp. Bei stdio claude neu starten |
| MCP server timeout | Start >5s usw. | MCP_TIMEOUT=10000 claude (ms). Pro Server: "timeout" in .mcp.json |
9. Berechtigungen und Tools
Die Familie „selbst im Bypass-Modus wird nach Erlaubnis gefragt". Der Kernpunkt: Deny-Regeln haben Vorrang vor Allow und Bypass.
| Symptom | Ursache | Lösung |
|---|---|---|
| Asked for permission even in bypass mode | Deny-Regeln gewinnen; gefährliche Operationen fragen immer nach (Circuit Breaker) | Deny-Regeln in /permissions prüfen und anpassen |
| Tool execution denied by PreToolUse hook | Ein Hook hat es mit Exit-Code 2 blockiert | Den Hook in .claude/settings.json prüfen. Ausgabe mit claude --debug ansehen |
Warum der Bypass trotzdem stoppt, siehe warum selbst im Bypass-Modus nach Erlaubnis gefragt wird; zum sicheren Berechtigungsdesign siehe Berechtigungsmodi und Sicherheit.
10. Sonstiges (thinking / Bild-PDF / IDE)
- thinking blocks cannot be modified (400): ein bekannter Bug, bei dem Extended-Thinking-Blöcke im Verlauf beschädigt werden. Zweimal Esc → /rewind, andernfalls eine neue Sitzung, und
claude update. Details: thinking-blocks-400-Fehler. - Could not check the pull request status: ein Problem mit der GitHub-Verbindung (oft
gh-Authentifizierung). Beginne mitgh auth status. Details: PR-Status-Fehler. - Image was too large / PDF too large: Bilder über 8000px an der langen Kante, PDFs über 100 Seiten / 32 MB werden abgelehnt. Zweimal Esc, um den Anhang zu entfernen; verkleinern oder per Zeilenbereich lesen. Große Dateien per Pfad referenzieren, statt sie einzufügen.
- VS-Code-Erweiterung verbindet sich nicht: bestätigen, dass
claude --versionim VS-Code-Terminal funktioniert. PATH prüfen, VS Code neu starten, die Erweiterung neu installieren.
11. Spickzettel: Fehler → Lösung
| Wenn das passiert | Versuche zuerst das |
|---|---|
| Ursache unbekannt / allgemein | claude doctor → /status → /context |
| Plötzlich zum Login aufgefordert | /status → (bei veraltetem Key) unset ANTHROPIC_API_KEY → /login |
| Rate-Limit erreicht | /usage → /model leichter → /compact → warten |
| Prompt is too long | /compact → /clear → große Dateien per Zeilenbereich lesen |
| 500/529/Timeout | status.claude.com prüfen → kurz warten → /model |
| command not found: claude | ~/.local/bin zum PATH hinzufügen |
| Keine Verbindung (Firmen-NW) | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP verbindet sich nicht | /mcp → URL/Rechte/Befehl prüfen → MCP_TIMEOUT |
| Selbst im Bypass gefragt | /permissions zum Prüfen der Deny-Regeln |
| Will es einfach behoben haben | claude update (die neueste Version behebt vieles) |
Fazit
Claude Code hat viele Fehler, aber der erste Schritt ist, die Ursache mit drei Befehlen einzugrenzen: claude doctor / /status / /context — das bringt die meisten Probleme wieder in Gang. Die häufigen Fälle sind vier Familien — Nutzung/Rate-Limits, Kontext-Überlauf, abgelaufene Authentifizierung, MCP-Verbindungsfehler — mit /usage, /compact, /login und /mcp als erste Lösungen.
Und der leicht übersehene, stärkste Schritt ist, es mit claude update aktuell zu halten. Claude Code wird schnell aktualisiert, und vergangene Bugs (wie das thinking-blocks-400) verschwinden oft schon durch das Anheben der Version. „Bei Problemen zuerst die drei Diagnosebefehle; wenn es nicht behoben ist, auf die neueste Version aktualisieren." Halte dich an dieses Muster, und du verschwendest keine Zeit mehr mit Fehlern.
Weiterführende Lektüre: thinking-blocks-400-Fehler, PR-Status-Prüffehler, Claude-Code-Token-Sparen, warum im Bypass-Modus nach Erlaubnis gefragt wird und was MCP ist.
FAQ
F. Ein Fehler ist aufgetaucht — was mache ich zuerst?
A. Führe claude doctor aus. Es prüft Installation, Einstellungen, MCP und Kontext in einem Durchgang. Schau dann auf /status (aktuelle Authentifizierung) und /context (was den Kontext frisst), dann erkennst du meist, ob es ein Authentifizierungs-, Kontext- oder Verbindungsproblem ist.
F. Ich erreiche Rate-Limits schnell. Was hilft?
A. Claude Code verbraucht das 10- bis 100-Fache der Tokens eines Chats, daher erreichst du sie früher als erwartet. Prüfe Limits und Reset-Zeit mit /usage, wechsle mit /model zu einem leichteren Modell, verkleinere den Verlauf mit /compact und deaktiviere ungenutztes MCP. Wenn das nicht reicht, einen höheren Plan (Max usw.) oder zusätzliche Credits in Betracht ziehen.
F. Es meldet „Invalid API key", obwohl mein Key korrekt sein sollte.
A. Die klassische Ursache ist eine veraltete Umgebungsvariable ANTHROPIC_API_KEY, die dein Abo überschreibt. Mit env | grep ANTHROPIC prüfen, unset ANTHROPIC_API_KEY (auch aus deinem Shell-Profil entfernen), dann /login und mit /status bestätigen.
F. Es verbindet sich nicht in meinem Firmennetz.
A. Zuerst die Erreichbarkeit mit curl -I https://api.anthropic.com bestätigen. Bei einem Proxy HTTPS_PROXY setzen; bei TLS-Inspektion NODE_EXTRA_CA_CERTS auf das CA-Zertifikat zeigen lassen. Verwende nicht NODE_TLS_REJECT_UNAUTHORIZED=0 — das ist gefährlich. Der richtige Weg ist, die IT zu bitten, api.anthropic.com freizugeben.
F. Nichts hilft — letzter Ausweg?
A. Mit claude update auf die neueste Version aktualisieren. Claude Code wird schnell aktualisiert, und bekannte Bugs verschwinden oft schon durch das Anheben der Version. Wenn es weiterhin fehlschlägt, per /feedback (enthält das Konversationsprotokoll) an Anthropic melden.
