Troubleshooting-FAQ

Oplossingen voor veelvoorkomende Synapse-problemen.

Ik kan niet inloggen

Symptomen

• POST /login retourneert 401
• "Invalid email or password"

Oplossingen

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

Ik ben mijn Mind Key kwijt

Symptomen

• Kan herinneringen niet benaderen
• Mind Key is verwijderd/verloren

Oplossingen

Mind Keys kunnen niet worden hersteld. U moet:

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

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

API-aanroepen retourneren 401

Symptomen

• Alle API-aanroepen retourneren 401 Unauthorized
• "Mind Key fehlt oder ungültig"

Oplossingen

1. Verifieer header-formaat: Authorization: Bearer mk_...
2. Controleer dat Mind Key begint met mk_ (niet eyJ wat JWT is)
3. Test direct:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

4. Mind Key kan zijn ingetrokken — maak een nieuwe mind aan

Zie Authenticatie.

API-aanroepen retourneren 404

Symptomen

• 404 Not Found
• "Route not found"

Oplossingen

1. Controleer geldige eindpunten: curl https://synapse.schaefer.zone/endpoints
2. Vergelijk URL exact — hoofdlettergevoelig, geen afsluitende slashes
3. Controleer HTTP-methode — GET /memory vs POST /memory zijn verschillend

API-aanroepen retourneren 429

Symptomen

• 429 Too Many Requests
• "Rate limit exceeded"

Oplossingen

1. Schakel over naar header-auth (geen ratelimit):

   # Niet
   curl ".../memory/recall?key=mk_..."
   
   # Wel
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Wacht Retry-After seconden als u ?key= moet gebruiken

Zie Ratelimits.

Memory-zoekopdracht retourneert geen resultaten

Symptomen

• GET /memory/search?q=... retourneert leeg
• Weet dat herinneringen bestaan

Oplossingen

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

Zie FTS5-zoekopdracht.

Herinneringen worden niet persistent gemaakt

Symptomen

• POST /memory retourneert succes
• GET /memory/recall toont ze niet

Oplossingen

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

Tools verschijnen niet in Claude Desktop

Symptomen

• Claude Desktop toont 0 tools
• Geen 🔌-icoon

Oplossingen

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

Zie MCP Troubleshooting.

Synapse is offline

Symptomen

• Kan synapse.schaefer.zone niet bereiken
• curl time-out

Oplossingen

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

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

Database-fouten

Symptomen

• 500 Internal Server Error
• "Database connection failed"

Oplossingen

Voor self-hosted:

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

Voor gehost: meld bij support.

Webhook vuurt niet

Symptomen

• Geregistreerde webhook maar ontvangt geen callbacks
• Geen POST naar uw URL

Oplossingen

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

Zie Webhooks API.

Cron-job draait niet

Symptomen

• Cron-job aangemaakt maar vuurt niet
• next_run wordt niet bijgewerkt

Oplossingen

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

Zie Cron & Scheduler.

Meer hulp nodig?

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

Volgende stappen

• Fouten & Foutafhandeling
• API-FAQ
• MCP Troubleshooting