Wer Claude Code dauerhaft benutzt, bleibt zwangsläufig irgendwann stecken. Dieses Kapitel ist kein Wörterbuch der Fehlermeldungen. Es dient dazu, sich eine Reihenfolge der Eingrenzung anzueignen, die vom Symptom zur Ursache hinabführt.
Wer die Reihenfolge hat, kann auch bei einer nie gesehenen Fehlermeldung beurteilen, „zu welcher Kategorie gehört das“. Die Artikel zu den Einzelfällen lesen Sie danach immer noch.
Was Sie tun, bevor Sie die Fehlermeldung suchen
Wenn es hakt, suchen die meisten die Fehlermeldung so, wie sie dasteht. Das hilft durchaus, aber fast immer kommen Sie schneller ans Ziel, wenn Sie vorher drei Dinge prüfen.
Wenn ja, liegt die Ursache nicht in der Umgebung, sondern in der letzten Veränderung. Ein länger gewordenes Gespräch, eine ergänzte Einstellung, ein gewechseltes Netz.
Jedes Mal heißt Konfiguration oder Umgebung. Nur manchmal heißt Andrang oder Leitung, und oft liegt die Ursache gar nicht bei Ihnen.
Beim Start, im Moment des Absendens oder mitten in der Antwort? Die Stelle des Anhaltens legt die Kategorie fast schon fest.
CHECK 3 wirkt am stärksten. Wissen Sie, wo in der Schleife aus sammeln → handeln → prüfen aus Kapitel 1 es angehalten hat, schrumpft die Kandidatenliste auf einen Schlag.
In eine von fünf Kategorien einsortieren
Die Fehler von Claude Code teilen sich nach dem Ort der Ursache in fünf. Bestimmen Sie zuerst, welche es ist.
Startet es?
Nein → ein Problem der App selbst (siehe den Nachtrag unten)
Ja
↓
Können Sie eine Anweisung senden?
Nein, es weist ab → 1. Authentifizierung
Ja
↓
Kommt eine Antwort zurück?
Nein, es kommt nichts an / es bricht ab → 2. Verbindung
Es spricht von einer „Grenze“ → 3. Nutzungsgrenzen
Es sagt „zu lang“ → 4. Kontext
Ja
↓
Es scheitert, sobald ein externes Werkzeug beteiligt ist → 5. Werkzeuge und Erweiterungen
Setzen Sie mit dieser Verzweigung Ihren Tipp und gehen Sie dann in den passenden Abschnitt unten. Jede Kategorie hat ihre eigene Form der Abhilfe, wer sie durcheinanderwirft, verliert einen halben Nachmittag.
1. Authentifizierung – es nimmt Ihnen nicht ab, wer Sie sind
Das Symptom lautet, dass Sie angeblich nicht angemeldet seien oder dass die Anmeldedaten als ungültig abgewiesen werden. Kennzeichnend ist, dass es anhält, bevor Sie eine Anweisung abschicken können.
Die Sitzung ist abgelaufen / Sie sind mit einem anderen Konto angemeldet / API-Schlüssel und Abonnement verwechselt / das Firmennetz blockiert den Datenverkehr der Anmeldung
Neu anmelden → prüfen, mit welchem Konto Sie angemeldet sind → über eine andere Leitung (etwa Tethering) versuchen. Hilft das Dritte, ist es Kategorie 2, die Verbindung
Weil in dieser Kategorie eine neue Anmeldung sehr oft hilft, verbeißt man sich leicht darin, wenn sie es einmal nicht tut. Nach zwei erfolglosen Versuchen verdächtigen Sie Kategorie 2. Auch der Datenverkehr der Anmeldung geht durchs Netz.
2. Verbindung – es kommt nichts an oder bricht ab
Das ist die Kategorie, die am leichtesten missverstanden wird. Es muss nicht an Ihrer Konfiguration liegen.
Die Symptome teilen sich in drei.
Proxy, TLS, Sperren im Firmennetz. Ein Problem auf der Seite der Umgebung, eingrenzbar über eine andere Leitung.
Der Dienst ist gerade überlaufen. Warten ist die richtige Antwort, wer an den Einstellungen dreht, behält nur die Nebenwirkungen.
Die Form, bei der die Verbindung während einer langen Antwort abreißt. Kürzere Ausgabeabschnitte lassen es mitunter nicht wieder auftreten.
Behandelt werden diese einzeln unter Abhilfe bei Verbindungs-, Proxy- und TLS-Fehlern, 529 Overloaded und Fehler 500 sowie Connection closed mid-response.
Versuchen Sie nicht, Andrang mit Einstellungen zu reparieren. Wer „scheitert manchmal“ reproduzieren will und dafür an zehn Stellen dreht, weiß am Ende nicht mehr, ob es an einer Änderung lag oder ob die Zeit es gerichtet hat. Warten Sie zuerst und versuchen Sie es erneut, um festzustellen, ob es jedes Mal passiert.
3. Nutzungsgrenzen – das Kontingent ist aufgebraucht
Die Kategorie, in der von einer erreichten Obergrenze die Rede ist. Das ist kein Fehler, sondern so vorgesehen, also ist nicht die Konfiguration zu reparieren, sondern die Art der Nutzung.
Wichtig ist hier, dass es nicht nur eine Art von Kontingent gibt. Ein Kontingent mit kurzem Zyklus und eines mit längerem Zyklus bestehen getrennt nebeneinander. Erholt sich das eine, während das andere noch aufgebraucht ist, steht alles weiterhin still. „Eben war es doch wieder da, und jetzt steht es schon wieder“ ist meistens genau das.
Ausführlich steht das unter Abhilfe bei usage limit reached und – mit einer Messung des Wochenkontingents – unter Was hinter dem vorzeitigen Zurücksetzen der Wochengrenze steckt. Wie Sie den Verbrauch selbst senken, behandelt Kapitel 7.
4. Kontext – die Eingabe ist zu lang
Die Kategorie, in der mit „zu lang“ abgewiesen wird. Betrachten Sie es als das Kontextfenster aus Kapitel 1, das hier unmittelbar als Symptom auftritt.
Den Verlauf zusammenfalten oder abschneiden und neu beginnen. An der Zäsur der Arbeit zu falten ist der Normalfall.
Riesige Dateien oder Logs nicht am Stück hineinkopieren. Nur die betreffende Stelle übergeben oder suchen lassen.
Die Abhilfe zum Symptom steht unter Ursachen und Abhilfe beim Fehler Prompt is too long, die Entscheidung, wann gefaltet wird, unter Sollte man /compact von Hand ausführen?.
Daneben gibt es Fälle, in denen eine Ausgabe wegen eines Richtlinienverstoßes angehalten wird. Das hat mit der Länge nichts zu tun, verwechseln Sie es also nicht. Das ist eine andere Form.
5. Werkzeuge und Erweiterungen – das Angeschlossene läuft nicht
Die Kategorie, die auftritt, nachdem Sie einen MCP-Server oder externe Werkzeuge ergänzt haben. Die Eingrenzung ist einfach: Sie sehen nach, ob es ohne sie wieder läuft.
Alle Erweiterungen entfernen
→ läuft wieder : Ursache ist eine Erweiterung. Einzeln zurücknehmen und den Schuldigen finden
→ läuft nicht : Die Erweiterungen sind unbeteiligt. Zurück zu 1 bis 4
Steht fest, dass eine Erweiterung die Ursache ist, geht es weiter zu Ursachen und Abhilfe bei MCP-Verbindungsfehlern. Fast immer ist es eines von dreien: das Format der Konfiguration, der Pfad des Startbefehls oder die Rechte.
Und zweifeln Sie hier nicht an der Klugheit von Claude. Ist die Erweiterung nicht verbunden, verhält sich Claude so, als gäbe es dieses Werkzeug nicht. Dass die Ursache von „ich habe es doch gesagt, und es tut es nicht“ eine fehlende Verbindung war, kommt häufig vor.
Ein Nachtrag – die App startet gar nicht erst
Wer nicht die Terminal-Fassung, sondern die Desktop-App benutzt, kann schon vor Claude Code hängen bleiben. Das ist keine der fünf Kategorien und deshalb aus dem Entscheidungsbaum herausgenommen.
Die Form, die unter Windows eine Reparatur verlangt, steht unter Reparaturschritte bei „Diese App kann nicht geöffnet werden“, die Form, die bei der Darstellung einfriert, unter Ursachen und Abhilfe beim Einfrieren mit GPU process gone.
Fünf Züge, wenn Sie immer noch feststecken
Wenn Sie die Kategorie nicht bestimmen können oder wenn es trotz Bestimmung nicht besser wird: Arbeiten Sie sich von oben nach unten durch. Sie sind vom Billigsten an geordnet.
Störungen, die vom Kontext herrühren, verschwinden damit. Der billigste Zug.
Andrang und Nutzungsgrenzen lösen sich allein dadurch. Die Einstellungen nicht anfassen.
Hilft das, steht fest, dass die Ursache im Netz Ihrer Umgebung liegt.
Die Eingrenzung für Kategorie 5. Zurücknehmen einzeln. Alles auf einmal zurückzunehmen bringt nichts.
In einem leeren Verzeichnis dasselbe versuchen. Tritt es dort nicht auf, liegt die Ursache im Projekt.
Ändern Sie immer nur eines auf einmal. Wer feststeckt, will vor lauter Ungeduld mehreres gleichzeitig ändern, aber dann wissen Sie hinterher nicht, was gewirkt hat, und fangen beim nächsten Auftreten desselben Symptoms wieder bei null an. Einen einzigen wirksamen Zug zu bestimmen ist auf lange Sicht mit Abstand billiger.
Wenn Sie von einer konkreten Fehlermeldung ausgehen wollen, dient Häufige Fehler und ihre Lösungen im Überblick als Register.
Zusammenfassung
- Bevor Sie die Fehlermeldung suchen, sehen Sie sich drei Dinge an: „Lief es eben noch?“, „Jedes Mal?“, „Wo hat es angehalten?“
- Die Ursachen teilen sich in fünf Kategorien: Authentifizierung, Verbindung, Nutzungsgrenzen, Kontext und Werkzeuge. Nicht durcheinander ausprobieren
- Bei Andrang und Nutzungsgrenzen ist Warten die richtige Antwort. Wer an den Einstellungen dreht, behält nur die Nebenwirkungen
- Es gibt nicht nur eine Art von Kontingent. Ein kurzer und ein langer Zyklus bestehen getrennt, es kann also nach der Erholung erneut stillstehen
- Die Kategorie der Erweiterungen grenzen Sie in einem Zug ein, indem Sie alle entfernen und sehen, ob es wieder läuft. Zurücknehmen einzeln
- Wenn Sie nicht herauskommen, fünf Züge in der Reihenfolge des Preises. Und immer nur eines auf einmal ändern
Wer aus Sackgassen herausfindet, kann als Nächstes entscheiden, wie weit er abgibt. Weiter zu Kapitel 5 „Rechte und Sicherheit“.