FAQ dépannage

Solutions aux problèmes courants de Synapse.

Je ne peux pas me connecter

Symptômes

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

Solutions

1. Vérifiez que l'email est correct — sensible à la casse
2. Vérifiez le mot de passe — minimum 6 caractères
3. Inscrivez-vous d'abord si vous n'avez pas de compte : POST /register
4. Réinitialisez le mot de passe (si SMTP configuré) via l'interface web

J'ai perdu ma Mind Key

Symptômes

• Impossible d'accéder aux mémoires
• La Mind Key a été supprimée/perdue

Solutions

Les Mind Keys ne peuvent pas être récupérées. Vous devez :

1. Vous connecter pour obtenir un JWT : POST /login
2. Lister les minds : GET /minds (avec JWT)
3. Créer un nouveau mind : POST /minds
4. Sauvegarder la nouvelle Mind Key
5. (Optionnel) Supprimer l'ancien mind : DELETE /minds/:id

Les données dans l'ancien mind sont perdues sauf si vous retrouvez la Mind Key.

Les appels API renvoient 401

Symptômes

• Tous les appels API renvoient 401 Unauthorized
• "Mind Key fehlt oder ungültig"

Solutions

1. Vérifiez le format de l'en-tête : Authorization: Bearer mk_...
2. Vérifiez que la Mind Key commence par mk_ (pas eyJ qui est un JWT)
3. Testez directement :

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

4. La Mind Key est peut-être révoquée — créez un nouveau mind

Voir Authentification.

Les appels API renvoient 404

Symptômes

• 404 Not Found
• "Route not found"

Solutions

1. Vérifiez les endpoints valides : curl https://synapse.schaefer.zone/endpoints
2. Comparez l'URL exactement — sensible à la casse, pas de barre oblique finale
3. Vérifiez la méthode HTTP — GET /memory vs POST /memory sont différents

Les appels API renvoient 429

Symptômes

• 429 Too Many Requests
• "Rate limit exceeded"

Solutions

1. Passez à l'auth par en-tête (sans limite de débit) :

   # À éviter
   curl ".../memory/recall?key=mk_..."
   
   # À faire
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Attendez Retry-After secondes si vous devez utiliser ?key=

Voir Limites de débit.

La recherche mémoire ne renvoie aucun résultat

Symptômes

• GET /memory/search?q=... renvoie vide
• Vous savez que des mémoires existent

Solutions

1. Vérifiez que les mémoires existent : GET /memory/recall
2. Vérifiez la syntaxe de recherche — FTS5 a une syntaxe spécifique
3. Essayez une requête plus simple — ?q=docker au lieu de ?q=docker+swarm+deployment
4. Utilisez la recherche sémantique pour les requêtes conceptuelles : GET /memory/semantic-search?q=...

Voir Recherche FTS5.

Les mémoires ne persistent pas

Symptômes

• POST /memory renvoie un succès
• GET /memory/recall ne les affiche pas

Solutions

1. Vérifiez que vous utilisez la même Mind Key — des clés différentes = des minds différents
2. Vérifiez la réponse — POST renvoie { "id": "mem_...", "status": "stored" }
3. Essayez GET /memory (liste JSON) au lieu de /memory/recall (texte)
4. Vérifiez le filtre — ?category= ou ?tag= peut les masquer

Les outils n'apparaissent pas dans Claude Desktop

Symptômes

• Claude Desktop affiche 0 outils
• Pas d'icône 🔌

Solutions

1. Redémarrez Claude Desktop complètement (Cmd+Q)
2. Vérifiez que le fichier de config est du JSON valide
3. Vérifiez Node.js 18+ installé
4. Exécutez MCP manuellement : npx -y synapse-mcp-api@latest
5. Consultez les logs : ~/Library/Logs/Claude/mcp.log

Voir Dépannage MCP.

Synapse est hors ligne

Symptômes

• Impossible d'atteindre synapse.schaefer.zone
• curl expire

Solutions

1. Vérifiez votre internet — essayez un autre site
2. Vérifiez la santé de Synapse : curl https://synapse.schaefer.zone/health
3. Attendez — peut être une panne temporaire ou un déploiement
4. Vérifiez la page de statut (si disponible)

Pour l'auto-hébergement : vérifiez le statut du conteneur Docker, la connexion à la base de données.

Erreurs de base de données

Symptômes

• 500 Internal Server Error
• "Database connection failed"

Solutions

Pour l'auto-hébergement :

1. Vérifiez que PostgreSQL fonctionne : docker ps | grep postgres
2. Vérifiez DATABASE_URL dans l'environnement
3. Vérifiez les migrations : npm run migrate:check
4. Vérifiez l'espace disque : df -h

Pour l'hébergement : signalez au support.

Le webhook ne se déclenche pas

Symptômes

• Webhook enregistré mais pas de rappels reçus
• Pas de POST vers votre URL

Solutions

1. Vérifiez que l'URL est accessible : curl -X POST your-url -d '{}'
2. Vérifiez le filtre d'événements — memory.* correspond à tous les événements de mémoire
3. Testez le webhook : POST /webhooks/:id/test
4. Vérifiez que le webhook est activé : GET /webhooks/:id
5. Vérifiez le SSL — Synapse requiert un HTTPS valide pour les URLs de webhook

Voir API Webhooks.

La tâche cron ne s'exécute pas

Symptômes

• Tâche cron créée mais ne se déclenche pas
• next_run ne se met pas à jour

Solutions

1. Vérifiez la syntaxe de planification — doit être un cron à 5 champs valide OU un entier en secondes
2. Vérifiez que l'endpoint est autorisé — doit être http(s), pas d'IP privées
3. Vérifiez que la tâche est activée : GET /cron
4. Attendez la prochaine heure planifiée — cron n'est pas instantané

Voir Cron & Scheduler.

Besoin d'aide supplémentaire ?

1. Consultez la documentation existante : https://synapse.schaefer.zone/docs
2. Recherchez dans les docs : GET /docs/search?q=your+question
3. Ouvrez un ticket : https://gitlab.com/schaefer-services/synapse/-/issues
4. Contact : voir la page /support

Prochaines étapes

• Erreurs & gestion des erreurs
• FAQ API
• Dépannage MCP