FAQ по устранению проблем

Решения типовых проблем Synapse.

Не могу войти

Симптомы

• POST /login возвращает 401
• «Invalid email or password»

Решения

1. Проверьте email — чувствителен к регистру
2. Проверьте пароль — минимум 6 символов
3. Сначала зарегистрируйтесь, если нет аккаунта: POST /register
4. Сбросьте пароль (если настроен SMTP) через веб-интерфейс

Я потерял Mind Key

Симптомы

• Не могу получить доступ к воспоминаниям
• Mind Key удалён/потерян

Решения

Mind Key нельзя восстановить. Необходимо:

1. Войти для получения JWT: POST /login
2. Получить список mind: GET /minds (с JWT)
3. Создать новый mind: POST /minds
4. Сохранить новый Mind Key
5. (Опционально) Удалить старый mind: DELETE /minds/:id

Данные в старом mind утеряны, если вы не сможете найти Mind Key.

API-вызовы возвращают 401

Симптомы

• Все API-вызовы возвращают 401 Unauthorized
• «Mind Key fehlt oder ungültig»

Решения

1. Проверьте формат заголовка: Authorization: Bearer mk_...
2. Проверьте, что Mind Key начинается с mk_ (а не eyJ — это JWT)
3. Протестируйте напрямую:

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

4. Mind Key мог быть отозван — создайте новый mind

См. Аутентификация.

API-вызовы возвращают 404

Симптомы

• 404 Not Found
• «Route not found»

Решения

1. Проверьте допустимые эндпоинты: curl https://synapse.schaefer.zone/endpoints
2. Сравните URL точно — чувствителен к регистру, без trailing-слешей
3. Проверьте HTTP-метод — GET /memory и POST /memory различаются

API-вызовы возвращают 429

Симптомы

• 429 Too Many Requests
• «Rate limit exceeded»

Решения

1. Перейдите на header-auth (без лимита):

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

2. Подождите Retry-After секунд, если необходимо использовать ?key=

См. Лимиты запросов.

Поиск по памяти возвращает пустой результат

Симптомы

• GET /memory/search?q=... возвращает пусто
• Знаю, что воспоминания есть

Решения

1. Убедитесь, что воспоминания существуют: GET /memory/recall
2. Проверьте синтаксис поиска — у FTS5 специфический синтаксис
3. Попробуйте более простой запрос — ?q=docker вместо ?q=docker+swarm+deployment
4. Используйте семантический поиск для концептуальных запросов: GET /memory/semantic-search?q=...

См. FTS5-поиск.

Воспоминания не сохраняются

Симптомы

• POST /memory возвращает успех
• GET /memory/recall не показывает их

Решения

1. Убедитесь, что тот же Mind Key — разные ключи = разные mind
2. Проверьте ответ — POST возвращает { "id": "mem_...", "status": "stored" }
3. Попробуйте GET /memory (JSON-список) вместо /memory/recall (текст)
4. Проверьте фильтр — ?category= или ?tag= могут скрывать их

Инструменты не появляются в Claude Desktop

Симптомы

• Claude Desktop показывает 0 инструментов
• Нет иконки 🔌

Решения

1. Полностью перезапустите Claude Desktop (Cmd+Q)
2. Проверьте, что файл конфигурации — валидный JSON
3. Убедитесь, что установлен Node.js 18+
4. Запустите MCP вручную: npx -y synapse-mcp-api@latest
5. Проверьте логи: ~/Library/Logs/Claude/mcp.log

См. Устранение проблем MCP.

Synapse недоступен

Симптомы

• Не удаётся подключиться к synapse.schaefer.zone
• curl тайм-аутится

Решения

1. Проверьте интернет — попробуйте другой сайт
2. Проверьте здоровье Synapse: curl https://synapse.schaefer.zone/health
3. Подождите — возможен временный сбой или развёртывание
4. Проверьте страницу статуса (если есть)

Для self-hosted: проверьте статус Docker-контейнера, подключение к БД.

Ошибки базы данных

Симптомы

• 500 Internal Server Error
• «Database connection failed»

Решения

Для self-hosted:

1. Проверьте, что PostgreSQL запущен: docker ps | grep postgres
2. Проверьте DATABASE_URL в окружении
3. Проверьте миграции: npm run migrate:check
4. Проверьте место на диске: df -h

Для хостинга: сообщите в поддержку.

Вебхук не срабатывает

Симптомы

• Зарегистрировали вебхук, но колбэки не приходят
• Нет POST на ваш URL

Решения

1. Убедитесь, что URL доступен: curl -X POST your-url -d '{}'
2. Проверьте фильтр событий — memory.* соответствует всем событиям памяти
3. Протестируйте вебхук: POST /webhooks/:id/test
4. Проверьте, что вебхук включён: GET /webhooks/:id
5. Проверьте SSL — Synapse требует валидный HTTPS для URL вебхуков

См. Webhooks API.

Cron-задача не запускается

Симптомы

• Создали cron-задачу, но она не срабатывает
• next_run не обновляется

Решения

1. Проверьте синтаксис расписания — должен быть валидный 5-полейный cron ИЛИ целое число секунд
2. Убедитесь, что эндпоинт разрешён — должен быть http(s), без приватных IP
3. Проверьте, что задача включена: GET /cron
4. Дождитесь следующего запланированного времени — cron не мгновенный

См. Cron и планировщик.

Нужно больше помощи?

1. Проверьте существующую документацию: https://synapse.schaefer.zone/docs
2. Поиск по документации: GET /docs/search?q=your+question
3. Создайте issue: https://gitlab.com/schaefer-services/synapse/-/issues
4. Контакт: см. страницу /support

Следующие шаги

• Ошибки и обработка ошибок
• FAQ по API
• Устранение проблем MCP