# FAQ Troubleshooting

Soluzioni ai problemi comuni di Synapse.

## Non riesco a fare login

### Sintomi

- `POST /login` restituisce 401
- "Invalid email or password"

### Soluzioni

1. **Verifichi che l'email sia corretta** — case sensitive
2. **Controlli la password** — minimo 6 caratteri
3. **Si registri prima** se non ha un account: `POST /register`
4. **Resetti la password** (se SMTP configurato) tramite la UI web

## Ho perso la mia Mind Key

### Sintomi

- Non riesco ad accedere alle memorie
- La Mind Key è stata eliminata/persa

### Soluzioni

Le Mind Key non possono essere recuperate. Deve:

1. Fare login per ottenere JWT: `POST /login`
2. Elencare le menti: `GET /minds` (con JWT)
3. Creare una nuova mente: `POST /minds`
4. Salvare la nuova Mind Key
5. (Opzionale) Eliminare la vecchia mente: `DELETE /minds/:id`

**I dati nella vecchia mente sono persi** a meno che non ritrovi la Mind Key.

## Le chiamate API restituiscono 401

### Sintomi

- Tutte le chiamate API restituiscono 401 Unauthorized
- "Mind Key fehlt oder ungültig"

### Soluzioni

1. **Verifichi il formato dell'header**: `Authorization: Bearer mk_...`
2. **Controlli che la Mind Key inizi con `mk_`** (non `eyJ` che è JWT)
3. **Testi direttamente**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **La Mind Key potrebbe essere revocata** — crei una nuova mente

Veda [Autenticazione](/docs/getting-started/authentication).

## Le chiamate API restituiscono 404

### Sintomi

- 404 Not Found
- "Route not found"

### Soluzioni

> [!CRITICAL]
> Non indovini i percorsi degli endpoint. Esistono solo i percorsi in
> `GET /endpoints`.

1. **Controlli gli endpoint validi**: `curl https://synapse.schaefer.zone/endpoints`
2. **Confronti l'URL esattamente** — case sensitive, nessuno slash finale
3. **Controlli il metodo HTTP** — `GET /memory` vs `POST /memory` sono diversi

## Le chiamate API restituiscono 429

### Sintomi

- 429 Too Many Requests
- "Rate limit exceeded"

### Soluzioni

1. **Passi all'auth tramite header** (nessun rate limit):
   ```bash
   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **Attenda `Retry-After` secondi** se deve usare `?key=`

Veda [Limiti di traffico](/docs/api/rate-limits).

## La ricerca nelle memorie non restituisce risultati

### Sintomi

- `GET /memory/search?q=...` restituisce vuoto
- Sa che le memorie esistono

### Soluzioni

1. **Verifichi che le memorie esistano**: `GET /memory/recall`
2. **Controlli la sintassi di ricerca** — FTS5 ha una sintassi specifica
3. **Provi una query più semplice** — `?q=docker` invece di `?q=docker+swarm+deployment`
4. **Usi la ricerca semantica** per query concettuali: `GET /memory/semantic-search?q=...`

Veda [Ricerca FTS5](/docs/concepts/fts5-search).

## Le memorie non persistono

### Sintomi

- POST /memory restituisce success
- GET /memory/recall non le mostra

### Soluzioni

1. **Verifichi la stessa Mind Key** — chiavi diverse = menti diverse
2. **Controlli la risposta** — POST restituisce `{ "id": "mem_...", "status": "stored" }`
3. **Provi GET /memory** (lista JSON) invece di /memory/recall (testo)
4. **Controlli i filtri** — `?category=` o `?tag=` potrebbero nasconderle

## Gli strumenti non appaiono in Claude Desktop

### Sintomi

- Claude Desktop mostra 0 strumenti
- Nessuna icona 🔌

### Soluzioni

1. **Riavvii completamente Claude Desktop** (Cmd+Q)
2. **Verifichi che il file di configurazione** sia JSON valido
3. **Controlli Node.js 18+** installato
4. **Esegua MCP manualmente**: `npx -y synapse-mcp-api@latest`
5. **Controlli i log**: `~/Library/Logs/Claude/mcp.log`

Veda [Troubleshooting MCP](/docs/mcp/troubleshooting).

## Synapse è offline

### Sintomi

- Non riesce a raggiungere synapse.schaefer.zone
- curl va in timeout

### Soluzioni

1. **Controlli la sua internet** — provi un altro sito
2. **Controlli la salute di Synapse**: `curl https://synapse.schaefer.zone/health`
3. **Attenda** — potrebbe essere un outage temporaneo o deployment
4. **Controlli la pagina di stato** (se disponibile)

Per self-hosted: controlli lo stato del container Docker, la connessione al
database.

## Errori del database

### Sintomi

- 500 Internal Server Error
- "Database connection failed"

### Soluzioni

Per self-hosted:

1. **Controlli che PostgreSQL sia in esecuzione**: `docker ps | grep postgres`
2. **Controlli DATABASE_URL** nell'env
3. **Controlli le migrazioni**: `npm run migrate:check`
4. **Controlli lo spazio su disco**: `df -h`

Per hosted: segnali al support.

## Webhook non si attiva

### Sintomi

- Webhook registrato ma non riceve callback
- Nessuna POST alla sua URL

### Soluzioni

1. **Verifichi che l'URL sia raggiungibile**: `curl -X POST your-url -d '{}'`
2. **Controlli il filtro eventi** — `memory.*` corrisponde a tutti gli eventi memory
3. **Testi il webhook**: `POST /webhooks/:id/test`
4. **Controlli che il webhook sia abilitato**: `GET /webhooks/:id`
5. **Verifichi SSL** — Synapse richiede HTTPS valido per le URL dei webhook

Veda [Webhooks API](/docs/api/webhooks).

## Il cron job non viene eseguito

### Sintomi

- Creato cron job ma non si attiva
- `next_run` non si aggiorna

### Soluzioni

1. **Controlli la sintassi della pianificazione** — deve essere cron a 5 campi valido OPP secondi interi
2. **Verifichi che l'endpoint sia consentito** — deve essere http(s), no IP privati
3. **Controlli che il job sia abilitato**: `GET /cron`
4. **Attenda il prossimo momento pianificato** — cron non è istantaneo

Veda [Cron & Scheduler](/docs/api/cron).

## Ha bisogno di altro aiuto?

1. **Controlli la documentazione esistente**: <https://synapse.schaefer.zone/docs>
2. **Cerchi nella documentazione**: `GET /docs/search?q=your+question`
3. **Apra un issue**: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. **Contatti**: veda la pagina `/support`

## Prossimi passi

- [Errori e gestione degli errori](/docs/api/errors)
- [FAQ API](/docs/faq/api-faq)
- [Troubleshooting MCP](/docs/mcp/troubleshooting)