{"title":"FAQ dépannage","slug":"troubleshooting","category":"faq","summary":"Solutions aux problèmes courants de Synapse — auth, réseau, données, déploiement.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":790,"read_minutes":4,"lang":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# FAQ dépannage\n\nSolutions aux problèmes courants de Synapse.\n\n## Je ne peux pas me connecter\n\n### Symptômes\n\n- `POST /login` renvoie 401\n- \"Invalid email or password\"\n\n### Solutions\n\n1. **Vérifiez que l'email est correct** — sensible à la casse\n2. **Vérifiez le mot de passe** — minimum 6 caractères\n3. **Inscrivez-vous d'abord** si vous n'avez pas de compte : `POST /register`\n4. **Réinitialisez le mot de passe** (si SMTP configuré) via l'interface web\n\n## J'ai perdu ma Mind Key\n\n### Symptômes\n\n- Impossible d'accéder aux mémoires\n- La Mind Key a été supprimée/perdue\n\n### Solutions\n\nLes Mind Keys ne peuvent pas être récupérées. Vous devez :\n\n1. Vous connecter pour obtenir un JWT : `POST /login`\n2. Lister les minds : `GET /minds` (avec JWT)\n3. Créer un nouveau mind : `POST /minds`\n4. Sauvegarder la nouvelle Mind Key\n5. (Optionnel) Supprimer l'ancien mind : `DELETE /minds/:id`\n\n**Les données dans l'ancien mind sont perdues** sauf si vous retrouvez la Mind Key.\n\n## Les appels API renvoient 401\n\n### Symptômes\n\n- Tous les appels API renvoient 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### Solutions\n\n1. **Vérifiez le format de l'en-tête** : `Authorization: Bearer mk_...`\n2. **Vérifiez que la Mind Key commence par `mk_`** (pas `eyJ` qui est un JWT)\n3. **Testez directement** :\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **La Mind Key est peut-être révoquée** — créez un nouveau mind\n\nVoir [Authentification](/docs/getting-started/authentication).\n\n## Les appels API renvoient 404\n\n### Symptômes\n\n- 404 Not Found\n- \"Route not found\"\n\n### Solutions\n\n> [!CRITICAL]\n> Ne devinez pas les chemins d'endpoints. Seuls les chemins dans `GET /endpoints`\n> existent.\n\n1. **Vérifiez les endpoints valides** : `curl https://synapse.schaefer.zone/endpoints`\n2. **Comparez l'URL exactement** — sensible à la casse, pas de barre oblique finale\n3. **Vérifiez la méthode HTTP** — `GET /memory` vs `POST /memory` sont différents\n\n## Les appels API renvoient 429\n\n### Symptômes\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### Solutions\n\n1. **Passez à l'auth par en-tête** (sans limite de débit) :\n ```bash\n # À éviter\n curl \".../memory/recall?key=mk_...\"\n \n # À faire\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Attendez `Retry-After` secondes** si vous devez utiliser `?key=`\n\nVoir [Limites de débit](/docs/api/rate-limits).\n\n## La recherche mémoire ne renvoie aucun résultat\n\n### Symptômes\n\n- `GET /memory/search?q=...` renvoie vide\n- Vous savez que des mémoires existent\n\n### Solutions\n\n1. **Vérifiez que les mémoires existent** : `GET /memory/recall`\n2. **Vérifiez la syntaxe de recherche** — FTS5 a une syntaxe spécifique\n3. **Essayez une requête plus simple** — `?q=docker` au lieu de `?q=docker+swarm+deployment`\n4. **Utilisez la recherche sémantique** pour les requêtes conceptuelles : `GET /memory/semantic-search?q=...`\n\nVoir [Recherche FTS5](/docs/concepts/fts5-search).\n\n## Les mémoires ne persistent pas\n\n### Symptômes\n\n- POST /memory renvoie un succès\n- GET /memory/recall ne les affiche pas\n\n### Solutions\n\n1. **Vérifiez que vous utilisez la même Mind Key** — des clés différentes = des minds différents\n2. **Vérifiez la réponse** — POST renvoie `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Essayez GET /memory** (liste JSON) au lieu de /memory/recall (texte)\n4. **Vérifiez le filtre** — `?category=` ou `?tag=` peut les masquer\n\n## Les outils n'apparaissent pas dans Claude Desktop\n\n### Symptômes\n\n- Claude Desktop affiche 0 outils\n- Pas d'icône 🔌\n\n### Solutions\n\n1. **Redémarrez Claude Desktop complètement** (Cmd+Q)\n2. **Vérifiez que le fichier de config est du JSON valide**\n3. **Vérifiez Node.js 18+** installé\n4. **Exécutez MCP manuellement** : `npx -y synapse-mcp-api@latest`\n5. **Consultez les logs** : `~/Library/Logs/Claude/mcp.log`\n\nVoir [Dépannage MCP](/docs/mcp/troubleshooting).\n\n## Synapse est hors ligne\n\n### Symptômes\n\n- Impossible d'atteindre synapse.schaefer.zone\n- curl expire\n\n### Solutions\n\n1. **Vérifiez votre internet** — essayez un autre site\n2. **Vérifiez la santé de Synapse** : `curl https://synapse.schaefer.zone/health`\n3. **Attendez** — peut être une panne temporaire ou un déploiement\n4. **Vérifiez la page de statut** (si disponible)\n\nPour l'auto-hébergement : vérifiez le statut du conteneur Docker, la connexion à la\nbase de données.\n\n## Erreurs de base de données\n\n### Symptômes\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### Solutions\n\nPour l'auto-hébergement :\n\n1. **Vérifiez que PostgreSQL fonctionne** : `docker ps | grep postgres`\n2. **Vérifiez DATABASE_URL** dans l'environnement\n3. **Vérifiez les migrations** : `npm run migrate:check`\n4. **Vérifiez l'espace disque** : `df -h`\n\nPour l'hébergement : signalez au support.\n\n## Le webhook ne se déclenche pas\n\n### Symptômes\n\n- Webhook enregistré mais pas de rappels reçus\n- Pas de POST vers votre URL\n\n### Solutions\n\n1. **Vérifiez que l'URL est accessible** : `curl -X POST your-url -d '{}'`\n2. **Vérifiez le filtre d'événements** — `memory.*` correspond à tous les événements de mémoire\n3. **Testez le webhook** : `POST /webhooks/:id/test`\n4. **Vérifiez que le webhook est activé** : `GET /webhooks/:id`\n5. **Vérifiez le SSL** — Synapse requiert un HTTPS valide pour les URLs de webhook\n\nVoir [API Webhooks](/docs/api/webhooks).\n\n## La tâche cron ne s'exécute pas\n\n### Symptômes\n\n- Tâche cron créée mais ne se déclenche pas\n- `next_run` ne se met pas à jour\n\n### Solutions\n\n1. **Vérifiez la syntaxe de planification** — doit être un cron à 5 champs valide OU un entier en secondes\n2. **Vérifiez que l'endpoint est autorisé** — doit être http(s), pas d'IP privées\n3. **Vérifiez que la tâche est activée** : `GET /cron`\n4. **Attendez la prochaine heure planifiée** — cron n'est pas instantané\n\nVoir [Cron & Scheduler](/docs/api/cron).\n\n## Besoin d'aide supplémentaire ?\n\n1. **Consultez la documentation existante** : \n2. **Recherchez dans les docs** : `GET /docs/search?q=your+question`\n3. **Ouvrez un ticket** : \n4. **Contact** : voir la page `/support`\n\n## Prochaines étapes\n\n- [Erreurs & gestion des erreurs](/docs/api/errors)\n- [FAQ API](/docs/faq/api-faq)\n- [Dépannage MCP](/docs/mcp/troubleshooting)\n","content_html":"

FAQ dépannage

\n

Solutions aux problèmes courants de Synapse.

\n

Je ne peux pas me connecter

\n

Symptômes

\n\n

Solutions

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

J'ai perdu ma Mind Key

\n

Symptômes

\n\n

Solutions

\n

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

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

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

\n

Les appels API renvoient 401

\n

Symptômes

\n\n

Solutions

\n
    \n
  1. Vérifiez le format de l'en-tête : Authorization: Bearer mk_...
    2. \n
  2. Vérifiez que la Mind Key commence par mk_ (pas eyJ qui est un JWT)
    3. \n
  3. Testez directement :
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. La Mind Key est peut-être révoquée — créez un nouveau mind
    5. \n
\n

Voir Authentification.

\n

Les appels API renvoient 404

\n

Symptômes

\n\n

Solutions

\n
Ne devinez pas les chemins d'endpoints. Seuls les chemins dans `GET /endpoints`\nexistent.
    \n
  1. Vérifiez les endpoints valides : curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Comparez l'URL exactement — sensible à la casse, pas de barre oblique finale
    3. \n
  3. Vérifiez la méthode HTTP — GET /memory vs POST /memory sont différents
    4. \n
\n

Les appels API renvoient 429

\n

Symptômes

\n\n

Solutions

\n
    \n
  1. Passez à l'auth par en-tête (sans limite de débit) :
    # À éviter\ncurl ".../memory/recall?key=mk_..."\n\n# À faire\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Attendez Retry-After secondes si vous devez utiliser ?key=
    3. \n
\n

Voir Limites de débit.

\n

La recherche mémoire ne renvoie aucun résultat

\n

Symptômes

\n\n

Solutions

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

Voir Recherche FTS5.

\n

Les mémoires ne persistent pas

\n

Symptômes

\n\n

Solutions

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

Les outils n'apparaissent pas dans Claude Desktop

\n

Symptômes

\n\n

Solutions

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

Voir Dépannage MCP.

\n

Synapse est hors ligne

\n

Symptômes

\n\n

Solutions

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

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

\n

Erreurs de base de données

\n

Symptômes

\n\n

Solutions

\n

Pour l'auto-hébergement :

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

Pour l'hébergement : signalez au support.

\n

Le webhook ne se déclenche pas

\n

Symptômes

\n\n

Solutions

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

Voir API Webhooks.

\n

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

\n

Symptômes

\n\n

Solutions

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

Voir Cron & Scheduler.

\n

Besoin d'aide supplémentaire ?

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

Prochaines étapes

\n\n","urls":{"html":"/docs/faq/troubleshooting","text":"/docs/faq/troubleshooting?format=text","json":"/docs/faq/troubleshooting?format=json","llm":"/docs/faq/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}