Zum Hauptinhalt springen

Fehlerbehebung bei Claude Code

Fortgeschritten
What you'll learn
  • Jedes Claude-Code-Problem in einem Schritt seiner Lösung zuordnen — mithilfe einer Symptomtabelle
  • Die beiden Diagnosebefehle ausführen, die die meisten Einrichtungsprobleme lösen, bevor du irgendetwas von Hand debuggst
  • Isolieren, ob ein Plugin, ein MCP-Server oder ein Hook die eigentliche Ursache ist
  • Die vier klassischen Laufzeitfehler beheben: hoher Speicherverbrauch, Abstürze, Kompaktierungs-Thrashing und eine Suche, die nichts findet
  • Die richtigen Belege sammeln, bevor du einen Fehlerbericht einreichst

Die Grundidee​

Fast jedes Claude-Code-Problem ist von einer von zwei Arten, und die haben völlig unterschiedliche Lösungen:

  • Deine Einrichtung ist falsch — ein Plugin, ein MCP-Server, ein Hook, eine Einstellungsdatei, eine fehlende Binärdatei. Die Lösung ist Konfiguration.
  • Die Sitzung ist überlastet — das Kontextfenster ist voll, eine riesige Datei hat den Speicher gesprengt, das Terminal kann nicht rendern. Die Lösung ist Hygiene.

Zu raten, welche von beiden vorliegt, ist der Punkt, an dem Leute einen Nachmittag verlieren. Die Tabelle unten erspart das Raten.

:::tip Eine andere Art von "seltsam"? Auf dieser Seite geht es darum, dass sich das Werkzeug falsch verhält — es startet nicht, es hängt, die Suche findet nichts. Wenn sich das Modell falsch verhält — es hat einen Fakt erfunden, eine Anweisung vergessen, etwas Vernünftiges verweigert — dann ist das eine andere Seite: Warum hat Claude das getan? :::

Hier anfangen: Symptom → wohin​

Finde dein Symptom. Lies nicht den Rest der Seite.

SymptomGehe zu
command not found, Installation schlägt fehl, EACCES, PATH- oder TLS-FehlerOffiziell: Installation & Anmeldung
Anmeldeschleifen, OAuth-Fehler, 403 Forbidden, "organization disabled"Offiziell: Anmeldung & Authentifizierung
Einstellungen greifen nicht, Hooks feuern nicht, MCP-Server laden nichtIsoliere deine Konfiguration unten
API Error: 5xx, 529 Overloaded, 429, ValidierungsfehlerFehler & Ratenbegrenzungen
model not found / "you may not have access to it"Aktuelle Modelle & Preise
VS Code oder JetBrains erkennt Claude nichtIDE-Integrationen
Hohe CPU- oder SpeicherauslastungSpeicher und CPU unten
Hängt, friert ein, reagiert nichtHänger und Einfrieren unten
Autocompact is thrashingKompaktierungs-Thrashing unten
Suche, @file, Agenten oder Skills finden keine DateienSuche findet nichts unten
Kästchen, Verschmierungen oder falsche Glyphen in einem IDE-TerminalVerstümmelter Terminaltext unten

Die zwei Befehle, die man zuerst ausführt​

Bevor du irgendetwas von Hand debuggst, führe die eingebaute Überprüfung aus. Sie diagnostiziert deine Installation, Einstellungen, Erweiterungen und Kontextnutzung — und schlägt Lösungen vor, die sie nach deiner Bestätigung anwenden kann.

Guided walkthrough1 of 3
  1. /doctor (Alias /checkup) inspiziert deine Installation, Einstellungen, Erweiterungen und Kontextnutzung und bietet dann an, die möglichen Lösungen anzuwenden. Das allein behebt die meisten Einrichtungsbeschwerden.

Eine kaputte Einrichtung diagnostizieren

# inside a session
/doctor

# if the session won't start at all
claude doctor

# check MCP server status
/mcp

Isoliere deine Konfiguration​

Wenn Einstellungen nicht greifen, Hooks nicht feuern oder etwas einfach daneben ist, lautet die Frage nie "was ist kaputt" — sondern welche deiner Anpassungen ist kaputt. Beantworte sie, indem du sie alle auf einmal entfernst.

--safe-mode startet Claude Code mit deaktivierten Anpassungen: keine Plugins, keine MCP-Server, keine Hooks.

Gegen eine saubere Konfiguration testen

claude --safe-mode

Das liefert dir ein klares Binärergebnis:

Sobald du weißt, dass es eine Anpassung ist, halbiere: aktiviere sie gruppenweise wieder, bis das Problem zurückkehrt. Die Verdächtigen, grob nach Häufigkeit als Übeltäter geordnet, sind MCP-Server, Hooks, Plugins und Einstellungen.

Pro tip
  • --safe-mode ist auch der richtige erste Schritt bei mysteriöser Langsamkeit, nicht nur bei völligem Versagen. Ein geschwätziger MCP-Server ist eine sehr häufige Ursache für beides.

Speicher und CPU​

Claude Code funktioniert mit den meisten Umgebungen, kann aber bei großen Codebasen echte Ressourcen verbrauchen. Arbeite diese der Reihe nach ab — sie sind vom Günstigsten zuerst sortiert.

Guided walkthrough1 of 5
  1. Führe /compact aus, um den Kontext zu verkleinern. Ein aufgeblähtes Kontextfenster ist die mit Abstand häufigste Ursache einer schweren Sitzung. Siehe /docs/claude-code/context-management.

Die /heapdump-Aufschlüsselung meldet Resident Set Size, JS-Heap, Array-Buffer und nicht zugeordneten nativen Speicher. Diese Aufteilung ist der nützliche Teil: Sie sagt dir, ob das Wachstum in JavaScript-Objekten oder tief unten im nativen Code steckt. Um zu untersuchen, was den Speicher am Leben hält, öffne die .heapsnapshot-Datei in den Chrome DevTools unter Memory → Load.

Hänger und Einfrieren​

Wenn Claude Code nicht mehr reagiert:

Guided walkthrough1 of 3
  1. Drücke Strg+C. Das bricht ab, was gerade läuft, ohne die Sitzung zu beenden.
Pro tip
  • Die Angst, eine lange Unterhaltung zu verlieren, ist der Grund, warum Leute einen Hänger aussitzen, statt ihn zu beenden. Tu das nicht — claude --resume im gleichen Verzeichnis holt die Sitzung zurück.

Kompaktierungs-Thrashing​

Dieser Fehler sieht alarmierend aus und ist in Wirklichkeit ein Schutz:

Autocompact is thrashing: the context refilled to the limit...

Er bedeutet, dass die automatische Kompaktierung erfolgreich war — und dann eine Datei oder Werkzeugausgabe sofort das gesamte Kontextfenster wieder gefüllt hat, mehrmals hintereinander. Claude Code hört mit dem Wiederholen auf, statt API-Aufrufe für eine Schleife zu verbrennen, die keine Fortschritte macht.

Die Ursache ist fast immer eine überdimensionierte Sache, die als Ganzes gelesen wird. Wähle die Lösung, die zu deiner Situation passt:

SituationLösung
Eine riesige Datei ist das ProblemBitte Claude, einen Zeilenbereich oder eine einzelne Funktion statt der ganzen Datei zu lesen
Der Kontext enthält eine große Ausgabe, die du nicht mehr brauchst/compact mit einem Fokus, der sie fallen lässt
Der große Lesevorgang ist wirklich notwendigVerschiebe ihn zu einem Subagenten, damit er ein separates Kontextfenster verbrennt
Die frühere Unterhaltung spielt keine Rolle mehr/clear

Mit einem Fokus kompaktieren, der den Ballast abwirft

/compact keep only the plan and the diff

Die Subagenten-Option ist die, die Leute vergessen, und sie ist oft die beste: Ein Subagent liest die riesige Datei in seinem Kontext und gibt nur die Schlussfolgerung an deinen zurück. Siehe Kontextverwaltung und Subagenten.

Suche findet nichts​

Wenn das Suchwerkzeug, @file-Erwähnungen, eigene Agenten oder eigene Skills Dateien nicht finden, von denen du weißt, dass sie existieren, kann die mitgelieferte ripgrep-Binärdatei auf deinem System wahrscheinlich nicht laufen. Die Lösung ist, das plattformeigene ripgrep zu installieren und Claude Code anzuweisen, es zu verwenden.

Guided walkthrough1 of 3
  1. macOS: brew install ripgrep — Ubuntu/Debian: sudo apt install ripgrep — Alpine: apk add ripgrep — Arch: pacman -S ripgrep — Windows: winget install BurntSushi.ripgrep.MSVC

Suche unter macOS reparieren

brew install ripgrep
export USE_BUILTIN_RIPGREP=0

Die WSL-Ausnahme​

Unter WSL sind unvollständige Suchergebnisse normalerweise keine kaputte Binärdatei. Das Lesen über die Windows/Linux-Dateisystemgrenze hinweg bringt eine Festplattenleistungseinbuße mit sich, sodass die Suche weniger Treffer zurückgibt als erwartet. Die Suche funktioniert weiterhin — sie liefert nur weniger.

Watch out
  • Unter WSL meldet claude doctor die Suche als OK, selbst wenn die Ergebnisse unvollständig sind. Eine grüne Überprüfung schließt dies nicht aus — genau das macht es schwer zu diagnostizieren.

Drei Auswege, der beste zuerst: verschiebe das Projekt auf das Linux-Dateisystem (/home/) statt /mnt/c/; führe Claude Code nativ unter Windows statt über WSL aus; oder verenge deine Suchen, damit weniger Dateien gescannt werden — "Suche nach der JWT-Validierungslogik im auth-service-Paket" schlägt "finde den Auth-Code".

Verstümmelter Terminaltext​

Zeichen, die als Kästchen, Verschmierungen oder falsche Glyphen im integrierten Terminal von VS Code, Cursor oder Devin Desktop erscheinen, sind ein Problem des GPU-Renderers, kein Schrift- oder Codierungsproblem.

Verstümmelte Glyphen in einem IDE-Terminal reparieren

/terminal-setup

Das setzt terminal.integrated.gpuAcceleration auf "off". Du kannst es stattdessen von Hand in deinen Editor-Einstellungen setzen und das Fenster neu laden — gleiches Ergebnis.

Große Tabellen werden abgeschnitten​

Eine Markdown-Tabelle mit über 200 Zeilen rendert ihre ersten 200, gefolgt von einer Zeile … N more rows not shown. Das ist nur eine Anzeigebegrenzung — die vollständige Tabelle ist weiterhin in der Unterhaltung, und /copy kopiert jede Zeile. Bei einer Tabelle, die zu groß ist, um sie überhaupt in einem Terminal zu lesen, bitte Claude, sie in eine Datei zu schreiben.

Einen guten Fehlerbericht einreichen​

Wenn hier nichts passt, melde es — aber bring Belege mit. Ein Bericht, der sagt "es ist langsam", kommt nirgendwohin; einer mit einem Heap-Snapshot und einem --safe-mode-Ergebnis wird behoben.

Guided walkthrough1 of 4
  1. Halte fest, was die Überprüfung sagt und welche MCP-Server tatsächlich geladen sind. Die Hälfte der gemeldeten Fehler wird hier beantwortet.
Key takeaways
  • Führe zuerst /doctor (Alias /checkup) aus — aus deiner Shell als claude doctor, wenn die Sitzung nicht startet. Es diagnostiziert Installation, Einstellungen, Erweiterungen und Kontextnutzung und kann Lösungen anwenden.
  • claude --safe-mode deaktiviert alle Anpassungen auf einmal. Ob das Problem das überlebt, ist der aussagekräftigste Fakt, den du sammeln kannst.
  • Hoher Speicher: /compact, zwischen Aufgaben neu starten, Build-Verzeichnisse in .gitignore, dann --safe-mode, dann /heapdump für Belege.
  • Ein Hänger ist keine verlorene Unterhaltung — Strg+C, dann das Terminal neu starten, dann claude --resume im gleichen Verzeichnis.
  • Autocompact-Thrashing bedeutet, dass ein überdimensionierter Lesevorgang das Fenster wieder füllt. Lies in Stücken, /compact mit einem Fokus, oder delegiere den Lesevorgang an einen Subagenten.
  • Wenn die Suche nichts findet, kann meist das mitgelieferte ripgrep nicht laufen: installiere das ripgrep deiner Plattform UND setze USE_BUILTIN_RIPGREP=0. Unter WSL ist es stattdessen eine Dateisystemgrenz-Einbuße — und claude doctor meldet die Suche weiterhin als OK.

Prüfe dich selbst

0/5
  1. Hooks feuern nicht und Einstellungen scheinen ignoriert zu werden. Was ist das aussagekräftigste Einzelne, das man versuchen kann?
  2. Claude Code hängt mitten in einer Aufgabe und Strg+C hilft nicht. Du schließt das Terminal. Was passiert mit deiner Unterhaltung?
  3. Du siehst 'Autocompact is thrashing: the context refilled to the limit...'. Was ist tatsächlich passiert?
  4. Du hast ripgrep mit brew installiert, weil @file-Erwähnungen nichts fanden, aber die Suche ist immer noch kaputt. Was hast du übersehen?
  5. Unter WSL gibt die Suche weniger Treffer als erwartet zurück, aber claude doctor meldet die Suche als OK. Was ist los?

Weiter​