FAQ з усунення несправностей

Рішення поширених проблем Synapse.

Не можу увійти

Симптоми

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

Рішення

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

Я втратив Mind Key

Симптоми

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

Рішення

Mind Keys неможливо відновити. Вам потрібно:

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 точно — чутливий до регістру, без кінцевих слешів
3. Перевірте HTTP-метод — GET /memory та POST /memory різні

API-виклики повертають 429

Симптоми

• 429 Too Many Requests
• «Rate limit exceeded»

Рішення

1. Перейдіть на автентифікацію через заголовок (без обмеження):

   # Не робіть
   curl ".../memory/recall?key=mk_..."
   
   # Робіть
   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

Для хостингу: зверніться до підтримки.

Webhook не спрацьовує

Симптоми

• Зареєстровано webhook, але не отримуєте зворотних викликів
• Немає POST на ваш URL

Рішення

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

Дивіться 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

Наступні кроки

• Помилки та обробка помилок
• API FAQ
• Усунення несправностей MCP