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:

   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.

Le chiamate API restituiscono 404

Sintomi

• 404 Not Found
• "Route not found"

Soluzioni

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):

   # 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.

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.

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.

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.

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.

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
• FAQ API
• Troubleshooting MCP