{"title":"Troubleshooting-FAQ","slug":"troubleshooting","category":"faq","summary":"Lösungen für häufige Synapse-Probleme — Auth, Netzwerk, Daten, Deployment.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":582,"read_minutes":3,"lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Troubleshooting-FAQ\n\nLösungen für häufige Synapse-Probleme.\n\n## Ich kann mich nicht einloggen\n\n### Symptome\n\n- `POST /login` liefert 401\n- „Invalid email or password\"\n\n### Lösungen\n\n1. **E-Mail verifizieren** — Case-sensitive\n2. **Passwort prüfen** — mindestens 6 Zeichen\n3. **Zuerst registrieren**, falls du kein Konto hast: `POST /register`\n4. **Passwort zurücksetzen** (falls SMTP konfiguriert) via Web-UI\n\n## Ich habe meinen Mind Key verloren\n\n### Symptome\n\n- Kann nicht auf Memories zugreifen\n- Mind Key wurde gelöscht/verloren\n\n### Lösungen\n\nMind Keys können nicht wiederhergestellt werden. Du musst:\n\n1. Einloggen, um JWT zu erhalten: `POST /login`\n2. Minds auflisten: `GET /minds` (mit JWT)\n3. Neuen Mind anlegen: `POST /minds`\n4. Neuen Mind Key speichern\n5. (Optional) Alten Mind löschen: `DELETE /minds/:id`\n\n**Daten im alten Mind sind verloren**, außer du findest den Mind Key.\n\n## API-Aufrufe liefern 401\n\n### Symptome\n\n- Alle API-Aufrufe liefern 401 Unauthorized\n- „Mind Key fehlt oder ungültig\"\n\n### Lösungen\n\n1. **Header-Format verifizieren**: `Authorization: Bearer mk_...`\n2. **Prüfen, dass Mind Key mit `mk_` beginnt** (nicht `eyJ`, das ist JWT)\n3. **Direkt testen**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key könnte widerrufen sein** — neuen Mind anlegen\n\nSiehe [Authentifizierung](/docs/getting-started/authentication).\n\n## API-Aufrufe liefern 404\n\n### Symptome\n\n- 404 Not Found\n- „Route not found\"\n\n### Lösungen\n\n> [!CRITICAL]\n> Rate keine Endpunkt-Pfade. Nur Pfade in `GET /endpoints` existieren.\n\n1. **Gültige Endpunkte prüfen**: `curl https://synapse.schaefer.zone/endpoints`\n2. **URL exakt vergleichen** — Case-sensitive, keine Trailing-Slashes\n3. **HTTP-Methode prüfen** — `GET /memory` vs `POST /memory` sind unterschiedlich\n\n## API-Aufrufe liefern 429\n\n### Symptome\n\n- 429 Too Many Requests\n- „Rate limit exceeded\"\n\n### Lösungen\n\n1. **Auf Header-Auth wechseln** (kein Rate Limit):\n ```bash\n # Don't\n curl \".../memory/recall?key=mk_...\"\n \n # Do\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **`Retry-After` Sekunden warten**, falls du `?key=` verwenden musst\n\nSiehe [Rate Limits](/docs/api/rate-limits).\n\n## Memory-Suche liefert keine Ergebnisse\n\n### Symptome\n\n- `GET /memory/search?q=...` liefert leer\n- weiß, dass Memories existieren\n\n### Lösungen\n\n1. **Verifizieren, dass Memories existieren**: `GET /memory/recall`\n2. **Such-Syntax prüfen** — FTS5 hat spezifische Syntax\n3. **Einfachere Query versuchen** — `?q=docker` statt `?q=docker+swarm+deployment`\n4. **Semantische Suche** für konzeptionelle Queries: `GET /memory/semantic-search?q=...`\n\nSiehe [FTS5-Suche](/docs/concepts/fts5-search).\n\n## Memories werden nicht persistiert\n\n### Symptome\n\n- POST /memory liefert Success\n- GET /memory/recall zeigt sie nicht\n\n### Lösungen\n\n1. **Selben Mind Key verifizieren** — verschiedene Keys = verschiedene Minds\n2. **Response prüfen** — POST liefert `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **GET /memory versuchen** (JSON-Liste) statt /memory/recall (Text)\n4. **Filter prüfen** — `?category=` oder `?tag=` könnten sie verbergen\n\n## Tools erscheinen nicht in Claude Desktop\n\n### Symptome\n\n- Claude Desktop zeigt 0 Tools\n- Kein 🔌-Icon\n\n### Lösungen\n\n1. **Claude Desktop vollständig neu starten** (Cmd+Q)\n2. **Config-Datei prüfen** — valides JSON\n3. **Node.js 18+** installiert prüfen\n4. **MCP manuell ausführen**: `npx -y synapse-mcp-api@latest`\n5. **Logs prüfen**: `~/Library/Logs/Claude/mcp.log`\n\nSiehe [MCP-Troubleshooting](/docs/mcp/troubleshooting).\n\n## Synapse ist offline\n\n### Symptome\n\n- synapse.schaefer.zone nicht erreichbar\n- curl läuft in Timeout\n\n### Lösungen\n\n1. **Internet prüfen** — andere Seite versuchen\n2. **Synapse-Health prüfen**: `curl https://synapse.schaefer.zone/health`\n3. **Warten** — könnte temporärer Ausfall oder Deployment sein\n4. **Status-Seite prüfen** (falls verfügbar)\n\nFür Self-Hosted: Docker-Container-Status und Datenbankverbindung prüfen.\n\n## Datenbankfehler\n\n### Symptome\n\n- 500 Internal Server Error\n- „Database connection failed\"\n\n### Lösungen\n\nFür Self-Hosted:\n\n1. **PostgreSQL läuft prüfen**: `docker ps | grep postgres`\n2. **DATABASE_URL** in Env prüfen\n3. **Migrationen prüfen**: `npm run migrate:check`\n4. **Speicherplatz prüfen**: `df -h`\n\nFür gehostet: an Support melden.\n\n## Webhook feuert nicht\n\n### Symptome\n\n- Webhook registriert, aber keine Callbacks erhalten\n- Kein POST an deine URL\n\n### Lösungen\n\n1. **URL erreichbar verifizieren**: `curl -X POST your-url -d '{}'`\n2. **Events-Filter prüfen** — `memory.*` matched alle Memory-Events\n3. **Webhook testen**: `POST /webhooks/:id/test`\n4. **Webhook aktiviert prüfen**: `GET /webhooks/:id`\n5. **SSL verifizieren** — Synapse erfordert gültiges HTTPS für Webhook-URLs\n\nSiehe [Webhooks-API](/docs/api/webhooks).\n\n## Cron-Job läuft nicht\n\n### Symptome\n\n- Cron-Job angelegt, aber er feuert nicht\n- `next_run` aktualisiert nicht\n\n### Lösungen\n\n1. **Schedule-Syntax prüfen** — muss gültiges 5-Feld-Cron ODER Integer-Sekunden sein\n2. **Endpunkt erlaubt verifizieren** — muss http(s) sein, keine privaten IPs\n3. **Job aktiviert prüfen**: `GET /cron`\n4. **Auf nächste geplante Zeit warten** — Cron ist nicht instant\n\nSiehe [Cron & Scheduler](/docs/api/cron).\n\n## Brauchst du weitere Hilfe?\n\n1. **Bestehende Doku prüfen**: \n2. **Doku durchsuchen**: `GET /docs/search?q=deine+frage`\n3. **Issue öffnen**: \n4. **Kontakt**: siehe `/support`-Seite\n\n## Nächste Schritte\n\n- [Errors & Fehlerbehandlung](/docs/api/errors)\n- [API-FAQ](/docs/faq/api-faq)\n- [MCP-Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

Troubleshooting-FAQ

\n

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

\n

Ich kann mich nicht einloggen

\n

Symptome

\n\n

Lösungen

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

Ich habe meinen Mind Key verloren

\n

Symptome

\n\n

Lösungen

\n

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

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

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

\n

API-Aufrufe liefern 401

\n

Symptome

\n\n

Lösungen

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

Siehe Authentifizierung.

\n

API-Aufrufe liefern 404

\n

Symptome

\n\n

Lösungen

\n
Rate keine Endpunkt-Pfade. Nur Pfade in `GET /endpoints` existieren.
    \n
  1. Gültige Endpunkte prüfen: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. URL exakt vergleichen — Case-sensitive, keine Trailing-Slashes
    3. \n
  3. HTTP-Methode prüfen — GET /memory vs POST /memory sind unterschiedlich
    4. \n
\n

API-Aufrufe liefern 429

\n

Symptome

\n\n

Lösungen

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

Siehe Rate Limits.

\n

Memory-Suche liefert keine Ergebnisse

\n

Symptome

\n\n

Lösungen

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

Siehe FTS5-Suche.

\n

Memories werden nicht persistiert

\n

Symptome

\n\n

Lösungen

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

Tools erscheinen nicht in Claude Desktop

\n

Symptome

\n\n

Lösungen

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

Siehe MCP-Troubleshooting.

\n

Synapse ist offline

\n

Symptome

\n\n

Lösungen

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

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

\n

Datenbankfehler

\n

Symptome

\n\n

Lösungen

\n

Für Self-Hosted:

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

Für gehostet: an Support melden.

\n

Webhook feuert nicht

\n

Symptome

\n\n

Lösungen

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

Siehe Webhooks-API.

\n

Cron-Job läuft nicht

\n

Symptome

\n\n

Lösungen

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

Siehe Cron & Scheduler.

\n

Brauchst du weitere Hilfe?

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

Nächste Schritte

\n\n","urls":{"html":"/docs/faq/troubleshooting","text":"/docs/faq/troubleshooting?format=text","json":"/docs/faq/troubleshooting?format=json","llm":"/docs/faq/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}