# 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**:
   ```bash
   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](/docs/getting-started/authentication).

## API-aanroepen retourneren 404

### Symptomen

- 404 Not Found
- "Route not found"

### Oplossingen

> [!CRITICAL]
> Raad geen eindpuntpaden. Alleen paden in `GET /endpoints` bestaan.

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):
   ```bash
   # 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](/docs/api/rate-limits).

## 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](/docs/concepts/fts5-search).

## 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](/docs/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](/docs/api/webhooks).

## 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](/docs/api/cron).

## 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](/docs/api/errors)
- [API-FAQ](/docs/faq/api-faq)
- [MCP Troubleshooting](/docs/mcp/troubleshooting)