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:

   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.

API-Aufrufe liefern 404

Symptome

• 404 Not Found
• „Route not found"

Lösungen

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):

   # 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.

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.

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.

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.

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.

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
• API-FAQ
• MCP-Troubleshooting