FAQ de solución de problemas

Soluciones a problemas comunes de Synapse.

No puedo iniciar sesión

Síntomas

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

Soluciones

1. Verifique que el email es correcto — sensible a mayúsculas/minúsculas
2. Compruebe la contraseña — mínimo 6 caracteres
3. Regístrese primero si no tiene cuenta: POST /register
4. Restablezca la contraseña (si SMTP está configurado) vía la interfaz web

Perdí mi Mind Key

Síntomas

• No puede acceder a las memorias
• El Mind Key se eliminó/perdió

Soluciones

Los Mind Keys no se pueden recuperar. Debe:

1. Iniciar sesión para obtener JWT: POST /login
2. Listar minds: GET /minds (con JWT)
3. Crear un nuevo mind: POST /minds
4. Guardar el nuevo Mind Key
5. (Opcional) Eliminar el mind antiguo: DELETE /minds/:id

Los datos del mind antiguo se pierden a menos que encuentre el Mind Key.

Las llamadas a la API devuelven 401

Síntomas

• Todas las llamadas a la API devuelven 401 Unauthorized
• "Mind Key fehlt oder ungültig"

Soluciones

1. Verifique el formato de la cabecera: Authorization: Bearer mk_...
2. Compruebe que el Mind Key empieza por mk_ (no eyJ, que es JWT)
3. Pruebe directamente:

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

4. El Mind Key puede estar revocado — cree un nuevo mind

Consulte Autenticación.

Las llamadas a la API devuelven 404

Síntomas

• 404 Not Found
• "Route not found"

Soluciones

1. Compruebe los endpoints válidos: curl https://synapse.schaefer.zone/endpoints
2. Compare la URL exactamente — sensible a mayúsculas/minúsculas, sin barras finales
3. Verifique el método HTTP — GET /memory vs POST /memory son diferentes

Las llamadas a la API devuelven 429

Síntomas

• 429 Too Many Requests
• "Rate limit exceeded"

Soluciones

1. Cambie a auth por cabecera (sin límite de frecuencia):

   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Espere Retry-After segundos si debe usar ?key=

Consulte Límites de frecuencia.

La búsqueda de memoria no devuelve resultados

Síntomas

• GET /memory/search?q=... devuelve vacío
• Sabe que existen memorias

Soluciones

1. Verifique que existen memorias: GET /memory/recall
2. Compruebe la sintaxis de búsqueda — FTS5 tiene sintaxis específica
3. Pruebe una consulta más simple — ?q=docker en lugar de ?q=docker+swarm+deployment
4. Use búsqueda semántica para consultas conceptuales: GET /memory/semantic-search?q=...

Consulte Búsqueda FTS5.

Las memorias no persisten

Síntomas

• POST /memory devuelve éxito
• GET /memory/recall no las muestra

Soluciones

1. Verifique el mismo Mind Key — claves diferentes = minds diferentes
2. Compruebe la respuesta — POST devuelve { "id": "mem_...", "status": "stored" }
3. Pruebe GET /memory (lista JSON) en lugar de /memory/recall (texto)
4. Revise el filtro — ?category= o ?tag= pueden estar ocultándolas

Las herramientas no aparecen en Claude Desktop

Síntomas

• Claude Desktop muestra 0 herramientas
• Sin icono 🔌

Soluciones

1. Reinicie Claude Desktop completamente (Cmd+Q)
2. Verifique que el archivo de configuración es JSON válido
3. Compruebe Node.js 18+ instalado
4. Ejecute MCP manualmente: npx -y synapse-mcp-api@latest
5. Revise los logs: ~/Library/Logs/Claude/mcp.log

Consulte Solución de problemas de MCP.

Synapse está fuera de línea

Síntomas

• No puede alcanzar synapse.schaefer.zone
• curl agota el tiempo de espera

Soluciones

1. Compruebe su internet — pruebe otro sitio
2. Verifique la salud de Synapse: curl https://synapse.schaefer.zone/health
3. Espere — puede ser una interrupción temporal o un despliegue
4. Consulte la página de estado (si está disponible)

Para autoalojamiento: compruebe el estado del contenedor Docker y la conexión a la base de datos.

Errores de base de datos

Síntomas

• 500 Internal Server Error
• "Database connection failed"

Soluciones

Para autoalojamiento:

1. Compruebe que PostgreSQL está corriendo: docker ps | grep postgres
2. Verifique DATABASE_URL en el entorno
3. Revise las migraciones: npm run migrate:check
4. Compruebe el espacio en disco: df -h

Para la versión alojada: reporte a soporte.

El webhook no se dispara

Síntomas

• Webhook registrado pero no recibe callbacks
• Sin POST a su URL

Soluciones

1. Verifique que la URL es alcanzable: curl -X POST your-url -d '{}'
2. Compruebe el filtro de eventos — memory.* coincide con todos los eventos de memoria
3. Pruebe el webhook: POST /webhooks/:id/test
4. Compruebe que el webhook está habilitado: GET /webhooks/:id
5. Verifique el SSL — Synapse requiere HTTPS válido para las URLs de webhook

Consulte API de Webhooks.

El trabajo cron no se ejecuta

Síntomas

• Trabajo cron creado pero no se dispara
• next_run no se actualiza

Soluciones

1. Compruebe la sintaxis de programación — debe ser cron de 5 campos válido O segundos enteros
2. Verifique que el endpoint está permitido — debe ser http(s), sin IPs privadas
3. Compruebe que el trabajo está habilitado: GET /cron
4. Espere a la próxima hora programada — cron no es instantáneo

Consulte Cron y Scheduler.

¿Necesita más ayuda?

1. Consulte la documentación existente: https://synapse.schaefer.zone/docs
2. Busque en la docs: GET /docs/search?q=your+question
3. Abra un issue: https://gitlab.com/schaefer-services/synapse/-/issues
4. Contacto: consulte la página /support

Próximos pasos

• Errores y manejo de errores
• FAQ de la API
• Solución de problemas de MCP