# Troubleshooting-FAQ

Lösungen für häufige Synapse-Probleme.

## Ich kann mich nicht einloggen

### Symptome

- `POST /login` liefert 401
- „Invalid email or password"

### Lösungen

1. **E-Mail verifizieren** — Case-sensitive
2. **Passwort prüfen** — mindestens 6 Zeichen
3. **Zuerst registrieren**, falls du kein Konto hast: `POST /register`
4. **Passwort zurücksetzen** (falls SMTP konfiguriert) via Web-UI

## Ich habe meinen Mind Key verloren

### Symptome

- Kann nicht auf Memories zugreifen
- Mind Key wurde gelöscht/verloren

### Lösungen

Mind Keys können nicht wiederhergestellt werden. Du musst:

1. Einloggen, um JWT zu erhalten: `POST /login`
2. Minds auflisten: `GET /minds` (mit JWT)
3. Neuen Mind anlegen: `POST /minds`
4. Neuen Mind Key speichern
5. (Optional) Alten Mind löschen: `DELETE /minds/:id`

**Daten im alten Mind sind verloren**, außer du findest den Mind Key.

## API-Aufrufe liefern 401

### Symptome

- Alle API-Aufrufe liefern 401 Unauthorized
- „Mind Key fehlt oder ungültig"

### Lösungen

1. **Header-Format verifizieren**: `Authorization: Bearer mk_...`
2. **Prüfen, dass Mind Key mit `mk_` beginnt** (nicht `eyJ`, das ist JWT)
3. **Direkt testen**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **Mind Key könnte widerrufen sein** — neuen Mind anlegen

Siehe [Authentifizierung](/docs/getting-started/authentication).

## API-Aufrufe liefern 404

### Symptome

- 404 Not Found
- „Route not found"

### Lösungen

> [!CRITICAL]
> Rate keine Endpunkt-Pfade. Nur Pfade in `GET /endpoints` existieren.

1. **Gültige Endpunkte prüfen**: `curl https://synapse.schaefer.zone/endpoints`
2. **URL exakt vergleichen** — Case-sensitive, keine Trailing-Slashes
3. **HTTP-Methode prüfen** — `GET /memory` vs `POST /memory` sind unterschiedlich

## API-Aufrufe liefern 429

### Symptome

- 429 Too Many Requests
- „Rate limit exceeded"

### Lösungen

1. **Auf Header-Auth wechseln** (kein Rate Limit):
   ```bash
   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **`Retry-After` Sekunden warten**, falls du `?key=` verwenden musst

Siehe [Rate Limits](/docs/api/rate-limits).

## Memory-Suche liefert keine Ergebnisse

### Symptome

- `GET /memory/search?q=...` liefert leer
- weiß, dass Memories existieren

### Lösungen

1. **Verifizieren, dass Memories existieren**: `GET /memory/recall`
2. **Such-Syntax prüfen** — FTS5 hat spezifische Syntax
3. **Einfachere Query versuchen** — `?q=docker` statt `?q=docker+swarm+deployment`
4. **Semantische Suche** für konzeptionelle Queries: `GET /memory/semantic-search?q=...`

Siehe [FTS5-Suche](/docs/concepts/fts5-search).

## Memories werden nicht persistiert

### Symptome

- POST /memory liefert Success
- GET /memory/recall zeigt sie nicht

### Lösungen

1. **Selben Mind Key verifizieren** — verschiedene Keys = verschiedene Minds
2. **Response prüfen** — POST liefert `{ "id": "mem_...", "status": "stored" }`
3. **GET /memory versuchen** (JSON-Liste) statt /memory/recall (Text)
4. **Filter prüfen** — `?category=` oder `?tag=` könnten sie verbergen

## Tools erscheinen nicht in Claude Desktop

### Symptome

- Claude Desktop zeigt 0 Tools
- Kein 🔌-Icon

### Lösungen

1. **Claude Desktop vollständig neu starten** (Cmd+Q)
2. **Config-Datei prüfen** — valides JSON
3. **Node.js 18+** installiert prüfen
4. **MCP manuell ausführen**: `npx -y synapse-mcp-api@latest`
5. **Logs prüfen**: `~/Library/Logs/Claude/mcp.log`

Siehe [MCP-Troubleshooting](/docs/mcp/troubleshooting).

## Synapse ist offline

### Symptome

- synapse.schaefer.zone nicht erreichbar
- curl läuft in Timeout

### Lösungen

1. **Internet prüfen** — andere Seite versuchen
2. **Synapse-Health prüfen**: `curl https://synapse.schaefer.zone/health`
3. **Warten** — könnte temporärer Ausfall oder Deployment sein
4. **Status-Seite prüfen** (falls verfügbar)

Für Self-Hosted: Docker-Container-Status und Datenbankverbindung prüfen.

## Datenbankfehler

### Symptome

- 500 Internal Server Error
- „Database connection failed"

### Lösungen

Für Self-Hosted:

1. **PostgreSQL läuft prüfen**: `docker ps | grep postgres`
2. **DATABASE_URL** in Env prüfen
3. **Migrationen prüfen**: `npm run migrate:check`
4. **Speicherplatz prüfen**: `df -h`

Für gehostet: an Support melden.

## Webhook feuert nicht

### Symptome

- Webhook registriert, aber keine Callbacks erhalten
- Kein POST an deine URL

### Lösungen

1. **URL erreichbar verifizieren**: `curl -X POST your-url -d '{}'`
2. **Events-Filter prüfen** — `memory.*` matched alle Memory-Events
3. **Webhook testen**: `POST /webhooks/:id/test`
4. **Webhook aktiviert prüfen**: `GET /webhooks/:id`
5. **SSL verifizieren** — Synapse erfordert gültiges HTTPS für Webhook-URLs

Siehe [Webhooks-API](/docs/api/webhooks).

## Cron-Job läuft nicht

### Symptome

- Cron-Job angelegt, aber er feuert nicht
- `next_run` aktualisiert nicht

### Lösungen

1. **Schedule-Syntax prüfen** — muss gültiges 5-Feld-Cron ODER Integer-Sekunden sein
2. **Endpunkt erlaubt verifizieren** — muss http(s) sein, keine privaten IPs
3. **Job aktiviert prüfen**: `GET /cron`
4. **Auf nächste geplante Zeit warten** — Cron ist nicht instant

Siehe [Cron & Scheduler](/docs/api/cron).

## Brauchst du weitere Hilfe?

1. **Bestehende Doku prüfen**: <https://synapse.schaefer.zone/docs>
2. **Doku durchsuchen**: `GET /docs/search?q=deine+frage`
3. **Issue öffnen**: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. **Kontakt**: siehe `/support`-Seite

## Nächste Schritte

- [Errors & Fehlerbehandlung](/docs/api/errors)
- [API-FAQ](/docs/faq/api-faq)
- [MCP-Troubleshooting](/docs/mcp/troubleshooting)