{"title":"Troubleshooting-FAQ","slug":"troubleshooting","category":"faq","summary":"Oplossingen voor veelvoorkomende Synapse-problemen — auth, netwerk, data, deployment.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":606,"read_minutes":3,"lang":"nl","translated":true,"requested_lang":"nl","content_markdown":"\n# Troubleshooting-FAQ\n\nOplossingen voor veelvoorkomende Synapse-problemen.\n\n## Ik kan niet inloggen\n\n### Symptomen\n\n- `POST /login` retourneert 401\n- \"Invalid email or password\"\n\n### Oplossingen\n\n1. **Verifieer dat e-mail correct is** — hoofdlettergevoelig\n2. **Controleer wachtwoord** — minimaal 6 tekens\n3. **Registreer eerst** als u geen account heeft: `POST /register`\n4. **Reset wachtwoord** (indien SMTP geconfigureerd) via de web-UI\n\n## Ik ben mijn Mind Key kwijt\n\n### Symptomen\n\n- Kan herinneringen niet benaderen\n- Mind Key is verwijderd/verloren\n\n### Oplossingen\n\nMind Keys kunnen niet worden hersteld. U moet:\n\n1. Inloggen om JWT te krijgen: `POST /login`\n2. Minds tonen: `GET /minds` (met JWT)\n3. Nieuwe mind aanmaken: `POST /minds`\n4. Nieuwe Mind Key opslaan\n5. (Optioneel) Oude mind verwijderen: `DELETE /minds/:id`\n\n**Data in de oude mind is verloren** tenzij u de Mind Key kunt vinden.\n\n## API-aanroepen retourneren 401\n\n### Symptomen\n\n- Alle API-aanroepen retourneren 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### Oplossingen\n\n1. **Verifieer header-formaat**: `Authorization: Bearer mk_...`\n2. **Controleer dat Mind Key begint met `mk_`** (niet `eyJ` wat JWT is)\n3. **Test direct**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key kan zijn ingetrokken** — maak een nieuwe mind aan\n\nZie [Authenticatie](/docs/getting-started/authentication).\n\n## API-aanroepen retourneren 404\n\n### Symptomen\n\n- 404 Not Found\n- \"Route not found\"\n\n### Oplossingen\n\n> [!CRITICAL]\n> Raad geen eindpuntpaden. Alleen paden in `GET /endpoints` bestaan.\n\n1. **Controleer geldige eindpunten**: `curl https://synapse.schaefer.zone/endpoints`\n2. **Vergelijk URL exact** — hoofdlettergevoelig, geen afsluitende slashes\n3. **Controleer HTTP-methode** — `GET /memory` vs `POST /memory` zijn verschillend\n\n## API-aanroepen retourneren 429\n\n### Symptomen\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### Oplossingen\n\n1. **Schakel over naar header-auth** (geen ratelimit):\n ```bash\n # Niet\n curl \".../memory/recall?key=mk_...\"\n \n # Wel\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Wacht `Retry-After` seconden** als u `?key=` moet gebruiken\n\nZie [Ratelimits](/docs/api/rate-limits).\n\n## Memory-zoekopdracht retourneert geen resultaten\n\n### Symptomen\n\n- `GET /memory/search?q=...` retourneert leeg\n- Weet dat herinneringen bestaan\n\n### Oplossingen\n\n1. **Verifieer dat herinneringen bestaan**: `GET /memory/recall`\n2. **Controleer zoeksyntaxis** — FTS5 heeft specifieke syntaxis\n3. **Probeer eenvoudigere query** — `?q=docker` in plaats van `?q=docker+swarm+deployment`\n4. **Gebruik semantisch zoeken** voor conceptuele query's: `GET /memory/semantic-search?q=...`\n\nZie [FTS5-zoekopdracht](/docs/concepts/fts5-search).\n\n## Herinneringen worden niet persistent gemaakt\n\n### Symptomen\n\n- POST /memory retourneert succes\n- GET /memory/recall toont ze niet\n\n### Oplossingen\n\n1. **Verifieer dezelfde Mind Key** — verschillende sleutels = verschillende minds\n2. **Controleer respons** — POST retourneert `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Probeer GET /memory** (JSON-lijst) in plaats van /memory/recall (tekst)\n4. **Controleer filter** — `?category=` of `?tag=` verbergen ze mogelijk\n\n## Tools verschijnen niet in Claude Desktop\n\n### Symptomen\n\n- Claude Desktop toont 0 tools\n- Geen 🔌-icoon\n\n### Oplossingen\n\n1. **Herstart Claude Desktop volledig** (Cmd+Q)\n2. **Verifieer configuratiebestand** is geldige JSON\n3. **Controleer Node.js 18+** geïnstalleerd\n4. **Draai MCP handmatig**: `npx -y synapse-mcp-api@latest`\n5. **Controleer logs**: `~/Library/Logs/Claude/mcp.log`\n\nZie [MCP Troubleshooting](/docs/mcp/troubleshooting).\n\n## Synapse is offline\n\n### Symptomen\n\n- Kan synapse.schaefer.zone niet bereiken\n- curl time-out\n\n### Oplossingen\n\n1. **Controleer uw internet** — probeer een andere site\n2. **Controleer Synapse-gezondheid**: `curl https://synapse.schaefer.zone/health`\n3. **Wacht** — kan tijdelijke storing of deployment zijn\n4. **Controleer statuspagina** (indien beschikbaar)\n\nVoor self-hosted: controleer Docker-containerstatus, databaseverbinding.\n\n## Database-fouten\n\n### Symptomen\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### Oplossingen\n\nVoor self-hosted:\n\n1. **Controleer dat PostgreSQL draait**: `docker ps | grep postgres`\n2. **Controleer DATABASE_URL** in env\n3. **Controleer migraties**: `npm run migrate:check`\n4. **Controleer schijfruimte**: `df -h`\n\nVoor gehost: meld bij support.\n\n## Webhook vuurt niet\n\n### Symptomen\n\n- Geregistreerde webhook maar ontvangt geen callbacks\n- Geen POST naar uw URL\n\n### Oplossingen\n\n1. **Verifieer dat URL bereikbaar is**: `curl -X POST your-url -d '{}'`\n2. **Controleer events-filter** — `memory.*` komt overeen met alle memory-events\n3. **Test webhook**: `POST /webhooks/:id/test`\n4. **Controleer dat webhook is ingeschakeld**: `GET /webhooks/:id`\n5. **Verifieer SSL** — Synapse vereist geldige HTTPS voor webhook-URL's\n\nZie [Webhooks API](/docs/api/webhooks).\n\n## Cron-job draait niet\n\n### Symptomen\n\n- Cron-job aangemaakt maar vuurt niet\n- `next_run` wordt niet bijgewerkt\n\n### Oplossingen\n\n1. **Controleer schema-syntaxis** — moet geldige 5-veld cron OF gehele seconden zijn\n2. **Verifieer dat eindpunt is toegestaan** — moet http(s) zijn, geen privé-IP's\n3. **Controleer dat job is ingeschakeld**: `GET /cron`\n4. **Wacht op volgende geplande tijd** — cron is niet onmiddellijk\n\nZie [Cron & Scheduler](/docs/api/cron).\n\n## Meer hulp nodig?\n\n1. **Controleer bestaande docs**: \n2. **Doorzoek docs**: `GET /docs/search?q=your+question`\n3. **Open issue**: \n4. **Contact**: zie `/support`-pagina\n\n## Volgende stappen\n\n- [Fouten & Foutafhandeling](/docs/api/errors)\n- [API-FAQ](/docs/faq/api-faq)\n- [MCP Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

Troubleshooting-FAQ

\n

Oplossingen voor veelvoorkomende Synapse-problemen.

\n

Ik kan niet inloggen

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Verifieer dat e-mail correct is — hoofdlettergevoelig
    2. \n
  2. Controleer wachtwoord — minimaal 6 tekens
    3. \n
  3. Registreer eerst als u geen account heeft: POST /register
    4. \n
  4. Reset wachtwoord (indien SMTP geconfigureerd) via de web-UI
    5. \n
\n

Ik ben mijn Mind Key kwijt

\n

Symptomen

\n\n

Oplossingen

\n

Mind Keys kunnen niet worden hersteld. U moet:

\n
    \n
  1. Inloggen om JWT te krijgen: POST /login
    2. \n
  2. Minds tonen: GET /minds (met JWT)
    3. \n
  3. Nieuwe mind aanmaken: POST /minds
    4. \n
  4. Nieuwe Mind Key opslaan
    5. \n
  5. (Optioneel) Oude mind verwijderen: DELETE /minds/:id
    6. \n
\n

Data in de oude mind is verloren tenzij u de Mind Key kunt vinden.

\n

API-aanroepen retourneren 401

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Verifieer header-formaat: Authorization: Bearer mk_...
    2. \n
  2. Controleer dat Mind Key begint met mk_ (niet eyJ wat JWT is)
    3. \n
  3. Test direct:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key kan zijn ingetrokken — maak een nieuwe mind aan
    5. \n
\n

Zie Authenticatie.

\n

API-aanroepen retourneren 404

\n

Symptomen

\n\n

Oplossingen

\n
Raad geen eindpuntpaden. Alleen paden in `GET /endpoints` bestaan.
    \n
  1. Controleer geldige eindpunten: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Vergelijk URL exact — hoofdlettergevoelig, geen afsluitende slashes
    3. \n
  3. Controleer HTTP-methode — GET /memory vs POST /memory zijn verschillend
    4. \n
\n

API-aanroepen retourneren 429

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Schakel over naar header-auth (geen ratelimit):
    # Niet\ncurl ".../memory/recall?key=mk_..."\n\n# Wel\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Wacht Retry-After seconden als u ?key= moet gebruiken
    3. \n
\n

Zie Ratelimits.

\n

Memory-zoekopdracht retourneert geen resultaten

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Verifieer dat herinneringen bestaan: GET /memory/recall
    2. \n
  2. Controleer zoeksyntaxis — FTS5 heeft specifieke syntaxis
    3. \n
  3. Probeer eenvoudigere query — ?q=docker in plaats van ?q=docker+swarm+deployment
    4. \n
  4. Gebruik semantisch zoeken voor conceptuele query's: GET /memory/semantic-search?q=...
    5. \n
\n

Zie FTS5-zoekopdracht.

\n

Herinneringen worden niet persistent gemaakt

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Verifieer dezelfde Mind Key — verschillende sleutels = verschillende minds
    2. \n
  2. Controleer respons — POST retourneert { "id": "mem_...", "status": "stored" }
    3. \n
  3. Probeer GET /memory (JSON-lijst) in plaats van /memory/recall (tekst)
    4. \n
  4. Controleer filter — ?category= of ?tag= verbergen ze mogelijk
    5. \n
\n

Tools verschijnen niet in Claude Desktop

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Herstart Claude Desktop volledig (Cmd+Q)
    2. \n
  2. Verifieer configuratiebestand is geldige JSON
    3. \n
  3. Controleer Node.js 18+ geïnstalleerd
    4. \n
  4. Draai MCP handmatig: npx -y synapse-mcp-api@latest
    5. \n
  5. Controleer logs: ~/Library/Logs/Claude/mcp.log
    6. \n
\n

Zie MCP Troubleshooting.

\n

Synapse is offline

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Controleer uw internet — probeer een andere site
    2. \n
  2. Controleer Synapse-gezondheid: curl https://synapse.schaefer.zone/health
    3. \n
  3. Wacht — kan tijdelijke storing of deployment zijn
    4. \n
  4. Controleer statuspagina (indien beschikbaar)
    5. \n
\n

Voor self-hosted: controleer Docker-containerstatus, databaseverbinding.

\n

Database-fouten

\n

Symptomen

\n\n

Oplossingen

\n

Voor self-hosted:

\n
    \n
  1. Controleer dat PostgreSQL draait: docker ps | grep postgres
    2. \n
  2. Controleer DATABASE_URL in env
    3. \n
  3. Controleer migraties: npm run migrate:check
    4. \n
  4. Controleer schijfruimte: df -h
    5. \n
\n

Voor gehost: meld bij support.

\n

Webhook vuurt niet

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Verifieer dat URL bereikbaar is: curl -X POST your-url -d '{}'
    2. \n
  2. Controleer events-filter — memory.* komt overeen met alle memory-events
    3. \n
  3. Test webhook: POST /webhooks/:id/test
    4. \n
  4. Controleer dat webhook is ingeschakeld: GET /webhooks/:id
    5. \n
  5. Verifieer SSL — Synapse vereist geldige HTTPS voor webhook-URL's
    6. \n
\n

Zie Webhooks API.

\n

Cron-job draait niet

\n

Symptomen

\n\n

Oplossingen

\n
    \n
  1. Controleer schema-syntaxis — moet geldige 5-veld cron OF gehele seconden zijn
    2. \n
  2. Verifieer dat eindpunt is toegestaan — moet http(s) zijn, geen privé-IP's
    3. \n
  3. Controleer dat job is ingeschakeld: GET /cron
    4. \n
  4. Wacht op volgende geplande tijd — cron is niet onmiddellijk
    5. \n
\n

Zie Cron & Scheduler.

\n

Meer hulp nodig?

\n
    \n
  1. Controleer bestaande docs: https://synapse.schaefer.zone/docs
    2. \n
  2. Doorzoek docs: GET /docs/search?q=your+question
    3. \n
  3. Open issue: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. Contact: zie /support-pagina
    5. \n
\n

Volgende stappen

\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"]}