Troubleshooting: Häufige Probleme lösen

Etwas funktioniert nicht. Das ist normal. Das passiert jedem. Der Unterschied zwischen einem Anfänger und einem erfahrenen Vibe Coder: Der Erfahrene weiß, wo er suchen muss.

Hier ist deine Referenz. Bookmark diese Seite. Du wirst sie brauchen.

Skill funktioniert nicht

Symptom: Du rufst einen Skill auf, aber nichts passiert — oder die AI ignoriert ihn.

Checkliste

1. Pfad prüfen

# Claude Code — Skills müssen hier liegen:
.claude/commands/skill-name.md

# NICHT hier:
.claude/skill-name.md
.claude/commands/skill-name.txt
commands/skill-name.md

2. Dateiendung prüfen

Muss .md sein
Nicht .mdx, nicht .txt, nicht .markdown

3. Tool neu starten

Claude Code: Terminal schließen, neues Terminal öffnen
Cursor: Editor komplett schließen und neu starten
Manchmal reicht das schon

4. Frontmatter prüfen (falls vorhanden)

# Korrekt:
---
description: "Beschreibung"
---

# Falsch (fehlende Bindestriche, Einrückungsfehler):
--
description: "Beschreibung"
---

5. Encoding prüfen

UTF-8 ohne BOM
In VS Code: Unten rechts steht das Encoding
Umlaute (ä, ö, ü) müssen korrekt angezeigt werden

6. Manueller Test Kopiere den Skill-Inhalt direkt in den Chat. Funktioniert er dann? Wenn ja: Dateiproblem. Wenn nein: Prompt-Problem.

AI verweigert die Arbeit mit Tokens

Symptom: Die AI sagt, sie könne nicht mit API-Tokens, Passwörtern oder sensiblen Daten arbeiten.

Ursache: AI-Modelle haben Sicherheitsrichtlinien und weigern sich manchmal, direkt mit Secrets zu arbeiten.

Lösung

Verwende Umgebungsvariablen statt direkter Token-Eingabe:

# FALSCH — AI wird sich möglicherweise weigern:
token = "7123456789:AAH1bGciOiJIUzI1NiJ..."

# RICHTIG — AI arbeitet problemlos damit:
import os
token = os.environ.get("TELEGRAM_BOT_TOKEN")

Erstelle eine .env-Datei:

TELEGRAM_BOT_TOKEN=dein-token-hier
EXA_API_KEY=dein-key-hier

Und sage der AI: "Nutze die Umgebungsvariable TELEGRAM_BOT_TOKEN aus der .env-Datei."

Token-Limit überschritten

Symptom: AI bricht mitten in der Antwort ab oder sagt, der Kontext sei zu groß.

Ursachen und Lösungen

1. Zu viel Kontext geladen

Reduziere die Anzahl geöffneter Dateien
Referenziere nur die Dateien, die wirklich nötig sind
Nutze spezifische Dateireferenzen statt "schau dir das ganze Projekt an"

2. Konversation zu lang

Starte eine neue Konversation
In Claude Code: exit und neu starten
In Cursor: Neuen Composer öffnen

3. Zu große Dateien

Teile große Dateien in kleinere auf
Lass die AI nur relevante Abschnitte lesen

Tipp: Wenn du merkst, dass die AI-Antworten schlechter werden, ist der Kontext wahrscheinlich überladen. Neuer Chat, frischer Start.

500 Internal Server Error

Symptom: API-Aufrufe geben einen 500-Fehler zurück.

Bedeutung: Der Server des Anbieters hat ein Problem. Das liegt nicht an dir.

Lösungen

Warten — 500-Fehler sind meistens temporär. 5 Minuten warten, erneut versuchen.
Status-Seite prüfen:
- Claude: status.anthropic.com
- OpenAI: status.openai.com
- Telegram: Downdetector
Retry-Logik einbauen — In deinem Code:

import time

def api_call_with_retry(func, max_retries=3):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if i < max_retries - 1:
                time.sleep(2 ** i)  # Exponential backoff
            else:
                raise e

Bot postet nicht im Kanal

Das häufigste Problem überhaupt. Systematische Diagnose:

Schritt 1: Bot ist Admin?

Öffne den Kanal → Info → Administratoren. Ist dein Bot aufgelistet? Wenn nicht: Bot als Admin hinzufügen.

Schritt 2: Bot hat Sende-Rechte?

Auch als Admin braucht der Bot explizit das Recht "Nachrichten senden". Prüfe die Admin-Einstellungen.

Schritt 3: Token korrekt?

Teste den Token isoliert:

curl "https://api.telegram.org/bot<TOKEN>/getMe"

Kommt eine Antwort mit Bot-Infos? Dann ist der Token gültig.

Schritt 4: Channel-ID korrekt?

Teste mit der korrekten ID:

curl "https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHANNEL_ID>&text=Test"

Häufige ID-Fehler:

ID vergessen mit -100 zu beginnen
Leerzeichen in der ID
Alte ID nach Kanal-Migration

Schritt 5: Fehler-Antwort lesen

Die Telegram-API gibt immer eine Fehlermeldung zurück. Lies sie:

Fehlermeldung	Bedeutung	Lösung
"chat not found"	ID falsch oder Bot nicht im Kanal	ID prüfen, Bot hinzufügen
"not enough rights"	Bot hat keine Sende-Rechte	Admin-Rechte prüfen
"Unauthorized"	Token ungültig	Token bei BotFather erneuern
"Too Many Requests"	Rate-Limit erreicht	Warten, Sende-Frequenz reduzieren

Token exponiert — was tun?

Sofort handeln. Keine Panik, aber auch kein Zögern.

Schritt-für-Schritt

Token widerrufen — Sofort bei @BotFather: /revoke → Bot auswählen
Neuen Token erhalten — BotFather gibt dir automatisch einen neuen
Token überall ersetzen:
- Lokale .env-Datei
- Server-Umgebungsvariablen (Railway, VPS)
- CI/CD-Secrets (GitHub Actions)
Git-History prüfen — Wenn der Token in einem Commit war:
```
# Prüfe, ob der Token in der History ist:
git log --all -p | grep "alter-token"
```
Wenn ja: Die gesamte Git-History bereinigen oder das Repository neu aufsetzen.
Bot-Aktivität prüfen — Wurden unautorisierte Nachrichten gesendet?

Prävention

.env in .gitignore — immer
Pre-Commit-Hooks, die nach Token-Mustern suchen
Secrets nie in Chats oder Screenshots teilen

Channel-ID nicht auffindbar

Methode 1: Web-Telegram (am zuverlässigsten)

Öffne web.telegram.org
Gehe zum Kanal
URL lesen: Die Zahl in der URL ist die ID
Füge -100 davor hinzu

Methode 2: Nachricht weiterleiten

Sende eine Nachricht im Kanal
Leite sie an @userinfobot oder @getidsbot weiter
Der Bot antwortet mit der ID

Methode 3: Bot-API

import requests

token = "dein-token"
# Sende zuerst eine Nachricht in den Kanal, dann:
r = requests.get(f"https://api.telegram.org/bot{token}/getUpdates")
print(r.json())
# Suche nach "chat":{"id": ...}

Cron-Job läuft nicht

Symptom: Dein geplanter Task wird nicht ausgeführt.

Diagnose

1. Cron-Syntax prüfen

# Jede Stunde:
0 * * * *

# Jeden Tag um 9:00:
0 9 * * *

# Alle 30 Minuten:
*/30 * * * *

# FALSCH (häufige Fehler):
* 9 * * *    # Jede Minute um 9 Uhr!
60 * * * *   # Ungültig — max 59

Nutze crontab.guru zur Überprüfung.

2. Zeitzone prüfen Server arbeiten oft in UTC. Wenn du 9:00 Berliner Zeit willst:

Sommerzeit: UTC+2 → 0 7 * * *
Winterzeit: UTC+1 → 0 8 * * *

3. Logs prüfen

# Auf dem Server:
journalctl -u dein-service --since "1 hour ago"

# Railway:
# Dashboard → Service → Logs

4. Script-Pfad prüfen Cron führt Befehle mit eingeschränktem PATH aus. Nutze absolute Pfade:

# FALSCH:
python script.py

# RICHTIG:
/usr/bin/python3 /home/user/project/script.py

Geplante Veröffentlichung fehlgeschlagen

Häufige Ursachen

Queue leer — Es gibt keinen Content zum Veröffentlichen
Formatierungsfehler — Der Content enthält ungültiges Markup
Rate-Limit — Zu viele Posts in kurzer Zeit
Server offline — Railway, VPS oder anderer Host ist down

Lösung

# Füge Logging hinzu, um Fehler zu identifizieren:
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

try:
    publish_post()
    logger.info("Post erfolgreich veröffentlicht")
except Exception as e:
    logger.error(f"Veröffentlichung fehlgeschlagen: {e}")

Railway-Probleme

Build schlägt fehl

Logs prüfen — Railway zeigt Build-Logs im Dashboard
requirements.txt prüfen — Alle Abhängigkeiten aufgelistet?
Python-Version — Railway nutzt standardmäßig Python 3.11+
Procfile prüfen:
```
worker: python main.py
```

Service startet, stürzt sofort ab

Umgebungsvariablen — Alle gesetzt? (TELEGRAM_BOT_TOKEN, etc.)
Port-Binding — Wenn Railway einen Port erwartet, aber dein Script keinen HTTP-Server startet
Speicher-Limit — Free-Tier hat 512MB RAM

Kosten explodieren

Sleep-Timer nutzen — Service pausieren, wenn nicht gebraucht
Cron statt Dauerbetrieb — Scheduled Tasks statt Always-On
Logs prüfen — Endlosschleifen verbrauchen Credits

Mehr zu Deployment: FAQ: Automatisierung und Deployment

Präventionstipps

Probleme vermeiden ist besser als Probleme lösen. Hier die wichtigsten Regeln:

1. Immer `.gitignore` pflegen

.env
.env.local
*.pyc
__pycache__/
node_modules/
.DS_Store

2. Immer Logging einbauen

Du kannst nicht fixen, was du nicht siehst. Logging ist nicht optional.

3. Immer in Staging testen

Teste nie in Produktion. Nutze einen privaten Testkanal, bevor du in den öffentlichen Kanal postest.

4. Immer Backups machen

# Vor größeren Änderungen:
git commit -am "Backup vor Umbau"

5. Immer kleine Schritte machen

Ändere eine Sache, teste, nächste Sache. Nicht zehn Dinge gleichzeitig ändern und dann debuggen.

6. Fehlermeldungen lesen

Klingt trivial. Ist es nicht. 80% aller Anfänger-Probleme werden gelöst, indem man die Fehlermeldung tatsächlich liest — statt sie zu ignorieren und im Forum zu fragen.

Immer noch ein Problem?

Wenn nichts aus dieser Liste hilft:

Fehlermeldung kopieren und in einer Suchmaschine suchen
Stack Overflow — fast jedes Problem wurde schon gelöst
AI fragen — beschreibe das Problem detailliert und füge die Fehlermeldung ein
Schau in unsere Guides für ausführliche Anleitungen

Das Wichtigste: Nicht aufgeben. Jeder erfahrene Entwickler hat dieselben Fehler gemacht. Der Unterschied ist nur, dass sie sie schon hinter sich haben.

Troubleshooting: Häufige Probleme lösen

Skill funktioniert nicht

Checkliste

AI verweigert die Arbeit mit Tokens

Lösung

Token-Limit überschritten

Ursachen und Lösungen

500 Internal Server Error

Lösungen

Bot postet nicht im Kanal

Schritt 1: Bot ist Admin?

Schritt 2: Bot hat Sende-Rechte?

Schritt 3: Token korrekt?

Schritt 4: Channel-ID korrekt?

Schritt 5: Fehler-Antwort lesen

Token exponiert — was tun?

Schritt-für-Schritt

Prävention

Channel-ID nicht auffindbar

Methode 1: Web-Telegram (am zuverlässigsten)

Methode 2: Nachricht weiterleiten

Methode 3: Bot-API

Cron-Job läuft nicht

Diagnose

Geplante Veröffentlichung fehlgeschlagen

Häufige Ursachen

Lösung

Railway-Probleme

Build schlägt fehl

Service startet, stürzt sofort ab

Kosten explodieren

Präventionstipps

1. Immer .gitignore pflegen

2. Immer Logging einbauen

3. Immer in Staging testen

4. Immer Backups machen

5. Immer kleine Schritte machen

6. Fehlermeldungen lesen

Immer noch ein Problem?

1. Immer `.gitignore` pflegen