Claude Code Masterkurs – KI-gestuetztes Programmieren lernen mit Anthropics Coding-Agent

Troubleshooting Pro

Level 3 | 30 Minuten

Diagnostiziere und löse die häufigsten Claude Code Probleme

Lernziele

Der 5-Schritte Diagnose-Check

Wenn Claude Code sich unerwartet verhält — schlechter Code, vergessene Anweisungen, langsame Antworten oder mysteriöse Fehler — gehe diese fünf Schritte systematisch durch. Die meisten Probleme lassen sich bereits in Schritt 1-2 identifizieren und beheben. Schritt 1: Verbindung prüfen. Ist Claude Code überhaupt mit der API verbunden? Tippfehler im API-Key, abgelaufene Authentifizierung oder Netzwerkprobleme sind die häufigste Ursache für komplett fehlende Antworten. Tippe /cost — wenn das funktioniert, ist die Verbindung in Ordnung. Schritt 2: Context-Gesundheit prüfen. Wie voll ist das Context Window? Tippe /context um den aktuellen Füllstand zu sehen. Über 70% Auslastung führt oft zu Qualitätsverlust. Lösung: /compact um den Kontext zu komprimieren, oder eine neue Session für frische Aufgaben. Schritt 3: Konfiguration prüfen. Welches Modell wird verwendet? Welche Permissions sind aktiv? Welche MCP Server sind verbunden? Ein versehentlich auf Haiku gesetztes Modell erklärt schlechte Code-Qualität. Ein nicht verbundener MCP Server erklärt fehlende Datenbank-Zugriffe. Schritt 4: Prompt-Qualität prüfen. Ist der Prompt klar, spezifisch und mit genug Kontext? Vage Prompts wie 'Fix das' führen zu vagen Ergebnissen. Reformuliere den Prompt mit konkreten Details und teste erneut. Schritt 5: Isolation testen. Starte eine komplett neue Session und teste die gleiche Aufgabe. Wenn es in der neuen Session funktioniert, war Context Rot das Problem. Wenn nicht, liegt es am Prompt, der Konfiguration oder dem Modell. Diese fünf Schritte lösen erfahrungsgemäß 90% aller Probleme. Für die restlichen 10% brauchst du die tiefergehenden Debug-Tools die in den folgenden Abschnitten beschrieben werden. Ein Profi-Tipp: Wenn du regelmäßig die gleichen Probleme hast, dokumentiere die Lösung in der CLAUDE.md oder als Troubleshooting-Skill. So hilft Claude sich selbst.

# 90% aller Probleme lösen sich mit diesen 5 Checks:

# 1. Installation prüfen
claude --version

# 2. Internet-Verbindung testen
ping claude.ai

# 3. API Key verifizieren
echo $ANTHROPIC_API_KEY

# 4. Session-State zurücksetzen (in Claude Code)
/clear

# 5. Konfiguration prüfen
claude config list

# Alles auf einmal: /doctor
/doctor
# → Prüft Installation, Version, Search-Funktionalität
# → Auto-Update Status
# → Ungültige Settings (JSON-Fehler, falsche Typen)
# → MCP Server Konfiguration
# → Keybinding-Probleme
# → Context-Usage Warnungen

Verbindungs-Probleme

Verbindungsprobleme sind die häufigste Fehlerquelle beim Start von Claude Code. Meistens liegt es an einem von drei Dingen: Authentifizierung, Netzwerk oder API-Konfiguration. Die Symptome sind eindeutig — Claude Code startet nicht, gibt eine Fehlermeldung aus, oder die Antworten bleiben komplett aus. Das häufigste Problem: Ein abgelaufener oder falscher API-Key. Prüfe ob der Key noch gültig ist und korrekt in der Umgebungsvariable ANTHROPIC_API_KEY gesetzt ist. Ein häufiger Fehler: Den Key in einer .env Datei zu haben die von der Shell nicht geladen wird. Teste mit 'echo $ANTHROPIC_API_KEY' ob der Key tatsächlich verfügbar ist. Das zweithäufigste Problem: Netzwerk-Einschränkungen. Firmen-Firewalls, VPNs und Proxy-Server können die Verbindung zu Anthropic's API blockieren. Wenn du hinter einem Proxy bist, konfiguriere die HTTP_PROXY und HTTPS_PROXY Umgebungsvariablen. Wenn die Firma bestimmte Domains blockiert, müssen api.anthropic.com und claude.ai freigegeben werden. Drittes Problem: Falsche API-Konfiguration. Wenn du Bedrock oder Vertex AI nutzt statt der direkten Anthropic-API, müssen die entsprechenden Umgebungsvariablen gesetzt sein (CLAUDE_CODE_USE_BEDROCK=1 oder CLAUDE_CODE_USE_VERTEX=1 plus die Cloud-spezifischen Credentials). Für MCP Server gibt es separate Verbindungsprobleme: Der Server startet nicht (falscher Pfad, fehlende Dependencies), der Server kann sich nicht authentifizieren (fehlender API-Key für den externen Service), oder der Server antwortet zu langsam (Timeout-Problem, erhöhe MCP_TIMEOUT). Der Verbose-Modus (claude --verbose) ist dein bester Freund bei Verbindungsproblemen: Er zeigt dir exakt welche Verbindungsversuche gemacht werden und wo sie scheitern. Damit findest du die Ursache meist in unter einer Minute.

HÄUFIGE VERBINDUNGSFEHLER
━━━━━━━━━━━━━━━━━━━━━━━━

❌ "Invalid API key"
Lösung:
  echo $ANTHROPIC_API_KEY              # Key prüfen
  claude config set apiKey sk-ant-...  # Neu setzen
  → console.anthropic.com prüfen

❌ "Rate limit exceeded"
Lösung:
  → Warten (Delay einhalten)
  → Anfrage-Frequenz reduzieren
  → Höheren Plan (Max 20x) upgraden

❌ "503 Service Unavailable"
Lösung:
  → status.anthropic.com prüfen
  → Warten und erneut versuchen
  → claude neu starten

❌ "Request timed out"
Lösung:
  → Internet-Verbindung prüfen
  → claude --timeout 120000 (längerer Timeout)
  → status.anthropic.com prüfen

Context-Probleme (häufigstes Problem!)

Context-Probleme sind die häufigste und gleichzeitig subtilste Ursache für schlechte Ergebnisse. Claude vergisst Entscheidungen, widerspricht sich, generiert inkonsistenten Code oder ignoriert deine Vorgaben — all das sind typische Symptome eines überfüllten oder schlecht gemanagten Context Windows. Die Grundursache ist fast immer die gleiche: Das Context Window ist zu voll. Selbst mit dem 1M Token Limit (Opus/Sonnet 4.6) füllt sich eine Session schneller als du denkst: Jede gelesene Datei, jede Antwort, jedes Zwischen-Ergebnis verbraucht Tokens. Nach 40-60 intensiven Nachrichten kann der Kontext bei 70-90% liegen — und ab 90% degradiert die Qualität merklich. Die Warnsignale erkennen: Claude wiederholt sich (es hat vergessen was es bereits gesagt hat). Claude widerspricht früheren Aussagen. Claude ignoriert Regeln aus der CLAUDE.md die es anfangs noch befolgt hat. Claude generiert Code der nicht zu den bereits generierten Dateien passt. Code-Qualität nimmt plötzlich ab. Sofort-Maßnahmen: /compact komprimiert die bisherige Konversation. Das fasst die gesamte History in eine kurze Zusammenfassung zusammen und gibt dir frischen Kontext-Platz. Bei schweren Problemen: /clear und eine komplett neue Session starten. Präventive Maßnahmen: Regelmäßig /compact nutzen (alle 15-20 Nachrichten). Große Dateien nur bei Bedarf laden (--include statt alles). MCP Server auf das Minimum beschränken. Neue Session für neue Aufgaben starten statt endlos weiterzuchatten. Das .claudeignore File ist eine oft übersehene Lösung: Schließe Verzeichnisse aus die Claude nicht braucht — node_modules, dist, build, .git, Testdaten, Bilder. Das verhindert dass Claude beim automatischen Scanning unnötig Kontext verbraucht. Langfristige Lösung: Eine gut gepflegte CLAUDE.md. Sie wird bei JEDER Session geladen und gibt Claude die wichtigsten Projektinformationen ohne dass du sie wiederholen musst. Das spart enormen Kontext-Platz.

DER CONTEXT-TODESSPIRALE
━━━━━━━━━━━━━━━━━━━━━━━

Phase 1: HONEYMOON 🌙
→ Alles funktioniert, Claude versteht alles

Phase 2: DEGRADATION 📉
→ Antworten werden langsamer
→ Claude beginnt sich zu wiederholen
→ "compacting conversation" erscheint

Phase 3: REGRESSION ⚠️
→ Claude vergisst kürzliche Änderungen
→ Führt bereits behobene Bugs wieder ein
→ Ignoriert Architektur-Entscheidungen

WARNSIGNALE ERKENNEN:
🟡 Antworten dauern merklich länger
🟡 Claude liest Dateien die es gerade gelesen hat
🟡 Fragen über schon besprochene Themen
🔴 "compacting conversation" Message
🔴 Claude widerspricht kürzlichen Entscheidungen
🔴 Implementiert Dinge die es gerade implementiert hat
# CONTEXT-PROBLEME LÖSEN:

# Sofort-Lösung: Komprimieren
/compact keep only function names and current errors

# Besser: Frisch starten
/clear

# Am besten: Strategisch arbeiten
# 1. Ein Feature pro Conversation
# 2. CLAUDE.md als permanentes Gedächtnis
# 3. Pläne in externe Dateien schreiben lassen:
> Write the implementation plan to SCRATCHPAD.md

# 4. Nach /clear den Plan wieder laden:
> Read SCRATCHPAD.md and continue from step 3

# 5. .claudeignore für große Projekte:
# .claudeignore
node_modules/
dist/
build/
*.log
__pycache__/
.git/objects/
# → Reduziert Context-Verbrauch um 40-60%!

Performance-Probleme

Wenn Claude Code langsam antwortet, Timeouts auftreten oder die Antworten unvollständig sind, liegt das meistens an einem von vier Faktoren: Überfüllter Context, zu viele MCP Server, falsches Modell, oder Netzwerk-Latenz. Die gute Nachricht: Alle vier Ursachen sind einfach zu beheben. Problem 1 — Überfüllter Context: Je voller das Context Window, desto langsamer die Verarbeitung. Claude muss mehr Informationen durcharbeiten, und die API-Antwort dauert länger. Lösung: /compact um den Kontext zu reduzieren. Idealerweise unter 50% Auslastung halten. Problem 2 — Zu viele MCP Server: Jeder aktive MCP Server fügt seine Tool-Beschreibungen zum Context hinzu — bei vielen Servern können das zehntausende Tokens sein. Lösung: Deaktiviere MCP Server die du gerade nicht brauchst. Die Empfehlung: Maximal 5-7 gleichzeitig aktive Server. Problem 3 — Falsches Modell: Opus ist deutlich langsamer als Sonnet, und Sonnet langsamer als Haiku. Wenn du für eine einfache Aufgabe Opus nutzt, wartest du unnötig lang. Lösung: Modell zur Aufgabe passend wählen. Haiku für schnelle Analysen, Sonnet für den Alltag, Opus nur für komplexe Aufgaben. Problem 4 — Netzwerk-Latenz: Besonders bei VPN-Verbindungen oder bei Nutzung von Bedrock/Vertex AI über Remote-Regionen kann die Netzwerk-Latenz erheblich sein. Lösung: Prüfe ob eine nähere API-Region verfügbar ist, oder wechsle vorübergehend auf direkte API-Nutzung. Für MCP-spezifische Performance-Probleme: Der MCP_TIMEOUT Parameter bestimmt wie lange Claude Code auf eine MCP-Server-Antwort wartet. Der Standard (5 Sekunden) kann für langsame Server zu kurz sein. Erhöhe ihn bei Timeout-Problemen. Der Debug-Modus (claude --verbose) zeigt dir Timing-Informationen für jeden Schritt — damit findest du den Bottleneck in Sekunden.

PERFORMANCE OPTIMIERUNG
━━━━━━━━━━━━━━━━━━━━━━

LANGSAME ANTWORTEN:
1. Context reduzieren → /compact
2. Dateien limitieren → Spezifisch referenzieren
3. Schnelleres Modell → claude --model haiku
4. /clear zwischen unabhängigen Tasks

HOHE KOSTEN:
1. /cost regelmäßig prüfen
2. /compact häufiger nutzen
3. Präzisere Prompts (weniger Exploration)
4. Haiku für einfache Sub-Tasks

HOHER SPEICHERVERBRAUCH:
1. Claude Code neu starten
2. /compact nutzen
3. Große Build-Verzeichnisse in .gitignore
4. Zwischen großen Tasks neu starten

ENDLOS-SCHLEIFEN:
1. Escape drücken zum Unterbrechen
2. Klare Grenzen setzen:
   > "Fix this in maximum 3 steps"
3. /clear und präziseren Prompt geben

Debug-Tools

Claude Code bietet mehrere eingebaute Werkzeuge die dir bei der Fehlersuche helfen. Von der einfachen Kostenanzeige bis zum vollständigen Debug-Log — je nach Problem brauchst du verschiedene Tools. Hier ist dein Debug-Werkzeugkasten. Das einfachste Tool: /cost zeigt den aktuellen Token-Verbrauch und die Kosten der Session. Wenn die Kosten unverhältnismäßig hoch sind, verbraucht Claude wahrscheinlich zu viele Tokens für Exploration oder steckt in einer Schleife. Das wichtigste Tool: /context zeigt den Füllstand des Context Windows. Du siehst: Gesamtkapazität, aktueller Verbrauch, Anteil von System-Prompt, Konversation, Tool-Ergebnissen und MCP-Beschreibungen. Damit identifizierst du sofort den größten Context-Verbraucher. Der Verbose-Modus: Starte Claude Code mit --verbose für detaillierte Logs. Du siehst jeden API-Aufruf, jede Tool-Nutzung, jede Datei die gelesen wird, und jede MCP-Server-Kommunikation. Das ist unverzichtbar für die Diagnose von Verbindungs- und Performance-Problemen. Der Debug-Modus: Noch detaillierter als verbose. Mit claude --debug bekommst du Low-Level-Informationen: Netzwerk-Requests, Token-Counting, Thinking-Logs und interne Entscheidungen. Nutze das nur wenn verbose nicht ausreicht. Für MCP-Debugging: /mcp zeigt den Status aller konfigurierten Server — verbunden, nicht verbunden, Fehler. Du siehst welche Tools jeder Server bereitstellt und ob es Kommunikationsprobleme gibt. Für Permission-Debugging: /permissions zeigt die aktuellen Berechtigungen — was erlaubt ist, was blockiert ist, und woher die Einstellung kommt (global, projekt, lokal). Wenn Claude eine Aktion nicht ausführen kann, findest du hier den Grund. Ein Profi-Tipp: Bei komplexen Problemen kombiniere die Tools. Erst /context prüfen (Context-Probleme?), dann /cost (Kosten-Anomalien?), dann /mcp (Server-Probleme?), dann verbose neu starten. Systematisch eingrenzen ist schneller als raten.

# Debug-Modus aktivieren:
CLAUDE_CODE_DEBUG=1 claude
# → Zeigt detaillierte Logs

# Status prüfen:
/status
# → Session-State, Usage Limits, Modell-Info

# Konfiguration prüfen:
claude config list
# → Alle aktiven Einstellungen

# Health Check:
/doctor
# → Umfassende Diagnose

# Logs ansehen:
cat ~/.claude/logs/claude-code.log

# Komplett zurücksetzen (Notfall):
rm -rf ~/.claude
claude config set apiKey sk-ant-...
# ⚠️ Löscht ALLE Settings, MCP-Server, Sessions!

# MCP Server debuggen:
/mcp
# → Status aller MCP Server
# → Fehler bei der Verbindung identifizieren

# Hook-Probleme debuggen:
CLAUDE_CODE_DEBUG=1 claude
# → Hook-Ausführung wird geloggt
# → Exit Codes sichtbar

Troubleshooting-Checkliste

Eine kompakte Checkliste die du bei jedem Problem durchgehen kannst. Sie ist sortiert nach Häufigkeit der Ursache — die wahrscheinlichste Ursache zuerst. In den meisten Fällen findest du das Problem in den ersten 3-4 Punkten. Checklist für schlechte Code-Qualität: Context Window über 70%? → /compact. CLAUDE.md vorhanden und aktuell? → prüfen/aktualisieren. Modell zu schwach (Haiku statt Sonnet)? → --model sonnet. Prompt zu vage? → spezifischer reformulieren. Zu viele Aufgaben gleichzeitig? → in Einzelschritte aufteilen. Checklist für Verbindungsprobleme: API-Key gültig? → echo $ANTHROPIC_API_KEY prüfen. Netzwerk OK? → curl api.anthropic.com testen. Proxy konfiguriert? → HTTP_PROXY prüfen. Cloud-Provider richtig? → Bedrock/Vertex Variablen prüfen. Claude Code aktuell? → claude update. Checklist für Performance: Context zu voll? → /compact. Zu viele MCP Server? → deaktivieren. Opus für einfache Aufgabe? → auf Sonnet wechseln. Netzwerk langsam? → VPN prüfen. Große Dateien geladen? → --include nutzen. Checklist für MCP-Probleme: Server verbunden? → /mcp prüfen. API-Key für Server gültig? → Umgebungsvariablen prüfen. Server-Timeout? → MCP_TIMEOUT erhöhen. npx Cache-Problem? → npx --cache-clear. Server manuell testbar? → isoliert starten. Checklist für inkonsistente Ergebnisse: Session zu lang? → neue Session starten. Widersprüchliche Anweisungen in CLAUDE.md? → aufräumen. MCP-Tools interferieren? → nicht-relevante Server deaktivieren. Falsches Thinking-Level? → 'think hard' für komplexe Aufgaben. Diese Checkliste solltest du ausdrucken oder als Bookmark speichern. In 90% der Fälle findest du das Problem damit in unter 2 Minuten.

TROUBLESHOOTING CHECKLISTE
━━━━━━━━━━━━━━━━━━━━━━━━━

□ Internet-Verbindung OK?
□ API Key gültig?
□ Node.js Version kompatibel (≥18)?
□ Claude Code aktuell? (claude --version)
□ Datei-Berechtigungen OK?
□ Context nicht gesättigt? (/compact oder /clear)
□ Hooks korrekt konfiguriert?
□ MCP Server erreichbar?
□ Settings-Dateien valides JSON?
□ Richtige Permissions gesetzt?

WENN NICHTS HILFT:
1. /doctor ausführen
2. Debug-Modus: CLAUDE_CODE_DEBUG=1 claude
3. GitHub Issues prüfen:
   github.com/anthropics/claude-code/issues
4. Community fragen:
   Discord & GitHub Discussions

Häufige Fehler vermeiden

Diese Fehler tauchen immer wieder auf — auch bei erfahrenen Nutzern. Wenn du sie kennst bevor du sie machst, sparst du dir Stunden an Debugging und Frustration. Hier sind die Top 8 der häufigsten Fehler. Fehler 1: Sessions zu lang laufen lassen. Nach 30+ Nachrichten ist der Context Window oft am Limit. Claude vergisst frühere Entscheidungen und generiert inkonsistenten Code. Faustregel: Alle 15-20 Nachrichten /compact, alle 30 Nachrichten neue Session. Fehler 2: Keine CLAUDE.md haben. Ohne CLAUDE.md muss Claude bei jeder Session das Projekt von Null verstehen. Mit CLAUDE.md hat es sofort den Kontext: Tech-Stack, Konventionen, Business-Logik. Investiere 30 Minuten in eine gute CLAUDE.md — sie spart dir Stunden. Fehler 3: Alle MCP Server gleichzeitig aktiv haben. Jeder Server frisst Context-Tokens. 10+ aktive Server können 40% deines Context Windows belegen bevor du die erste Frage stellst. Aktiviere nur was du gerade brauchst. Fehler 4: Opus für alles nutzen. Opus ist das beste Modell, aber auch das teuerste und langsamste. Für 80% der Aufgaben liefert Sonnet gleich gute Ergebnisse in der halben Zeit zum halben Preis. Fehler 5: Keine .claudeignore haben. Ohne Ignore-Datei scannt Claude alles — auch node_modules, dist, build, Bilder und andere irrelevante Dateien. Das verschwendet Context und verlangsamt die Analyse. Fehler 6: Fehler nicht reproduzieren. 'Es geht nicht' ist kein hilfreicher Bug-Report — auch nicht an Claude. Beschreibe genau: Was hast du getan, was ist passiert, was hast du erwartet? Fehler 7: Claude blind vertrauen. Claude produziert meist guten Code, aber nicht immer perfekten. Prüfe die Ergebnisse, lass Tests laufen, reviewe sicherheitskritischen Code manuell. Fehler 8: Updates ignorieren. Claude Code wird regelmäßig aktualisiert. Neue Versionen bringen nicht nur Features sondern auch Bug-Fixes und Sicherheits-Patches. 'claude update' regelmäßig ausführen.

Zusammenfassung