# Troubleshooting: Häufige Probleme lösen

> Lösungen für die häufigsten Probleme — Skill funktioniert nicht, Bot postet nicht, Token-Fehler und mehr.

- URL: https://thevibe-coding.de/kurs/troubleshooting
- Typ: kurs | Veroeffentlicht: 2026-02-24 | Aktualisiert: 2026-07-17
- Autor: VIBE CODING | Site: VIBE CODING — thevibe-coding.de

---

# 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 und Dateinamen prüfen**
```
# Claude Code — Skills müssen hier liegen:
.claude/skills/skill-name/SKILL.md     # projektspezifisch
~/.claude/skills/skill-name/SKILL.md   # global

# NICHT hier:
.claude/skills/skill-name.md    # Ordner fehlt
.claude/skills/skill-name/skill-name.md   # Datei muss SKILL.md heißen
.claude/commands/skill-name.md  # das sind Slash-Commands, keine Skills
```

Die drei häufigsten Fehler:
- **Datei nicht `SKILL.md` genannt** — der Name ist Pflicht, exakt so
- **YAML-Frontmatter fehlt** — ohne `name` und `description` wird der Skill nicht registriert
- **description zu vage** — Skills sind model-invoked: Claude lädt sie nur, wenn die Aufgabe zur description passt. Eine vage description bedeutet, der Skill wird nie geladen. Schreibe rein, WANN er verwendet werden soll.

**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)
```yaml
# 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:

```python
# 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

1. **Warten** — 500-Fehler sind meistens temporär. 5 Minuten warten, erneut versuchen.
2. **Status-Seite prüfen:**
   - Claude: status.anthropic.com
   - OpenAI: status.openai.com
   - Telegram: Downdetector
3. **Retry-Logik einbauen** — In deinem Code:
```python
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:
```bash
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:
```bash
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

1. **Token widerrufen** — Sofort bei @BotFather: `/revoke` → Bot auswählen
2. **Neuen Token erhalten** — BotFather gibt dir automatisch einen neuen
3. **Token überall ersetzen:**
   - Lokale `.env`-Datei
   - Server-Umgebungsvariablen (Railway, VPS)
   - CI/CD-Secrets (GitHub Actions)
4. **Git-History prüfen** — Wenn der Token in einem Commit war:
   ```bash
   # 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.
5. **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)
1. Öffne web.telegram.org
2. Gehe zum Kanal
3. URL lesen: Die Zahl in der URL ist die ID
4. Füge `-100` davor hinzu

### Methode 2: Nachricht weiterleiten
1. Sende eine Nachricht im Kanal
2. Leite sie an `@userinfobot` oder `@getidsbot` weiter
3. Der Bot antwortet mit der ID

### Methode 3: Bot-API
```python
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](https://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**
```bash
# 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:
```bash
# FALSCH:
python script.py

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

---

## Geplante Veröffentlichung fehlgeschlagen

### Häufige Ursachen

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

### Lösung
```python
# 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
1. **Logs prüfen** — Railway zeigt Build-Logs im Dashboard
2. **requirements.txt prüfen** — Alle Abhängigkeiten aufgelistet?
3. **Python-Version** — Railway nutzt standardmäßig Python 3.11+
4. **Procfile prüfen:**
   ```
   worker: python main.py
   ```

### Service startet, stürzt sofort ab
1. **Umgebungsvariablen** — Alle gesetzt? (TELEGRAM_BOT_TOKEN, etc.)
2. **Port-Binding** — Wenn Railway einen Port erwartet, aber dein Script keinen HTTP-Server startet
3. **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](/kurs/faq-automatisierung)

---

## 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
```bash
# 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:

1. **Fehlermeldung kopieren** und in einer Suchmaschine suchen
2. **Stack Overflow** — fast jedes Problem wurde schon gelöst
3. **AI fragen** — beschreibe das Problem detailliert und füge die Fehlermeldung ein
4. Schau in unsere [Guides](/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.