{"title":"FAQ з усунення несправностей","slug":"troubleshooting","category":"faq","summary":"Рішення поширених проблем Synapse — автентифікація, мережа, дані, розгортання.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":621,"read_minutes":3,"lang":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# FAQ з усунення несправностей\n\nРішення поширених проблем Synapse.\n\n## Не можу увійти\n\n### Симптоми\n\n- `POST /login` повертає 401\n- «Invalid email or password»\n\n### Рішення\n\n1. **Перевірте, що email правильний** — чутливий до регістру\n2. **Перевірте пароль** — мінімум 6 символів\n3. **Спочатку зареєструйтесь**, якщо немає облікового запису: `POST /register`\n4. **Скиньте пароль** (якщо налаштовано SMTP) через веб-інтерфейс\n\n## Я втратив Mind Key\n\n### Симптоми\n\n- Не можу доступатися до спогадів\n- Mind Key видалено/втрачено\n\n### Рішення\n\nMind Keys неможливо відновити. Вам потрібно:\n\n1. Увійти, щоб отримати JWT: `POST /login`\n2. Вивести список mind-ів: `GET /minds` (з JWT)\n3. Створити новий mind: `POST /minds`\n4. Зберегти новий Mind Key\n5. (Опціонально) Видалити старий mind: `DELETE /minds/:id`\n\n**Дані у старому mind-і втрачено**, якщо ви не зможете знайти Mind Key.\n\n## API-виклики повертають 401\n\n### Симптоми\n\n- Усі API-виклики повертають 401 Unauthorized\n- «Mind Key fehlt oder ungültig»\n\n### Рішення\n\n1. **Перевірте формат заголовка**: `Authorization: Bearer mk_...`\n2. **Перевірте, що Mind Key починається з `mk_`** (не `eyJ`, що є JWT)\n3. **Протестуйте напряму**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key може бути відкликано** — створіть новий mind\n\nДивіться [Автентифікацію](/docs/getting-started/authentication).\n\n## API-виклики повертають 404\n\n### Симптоми\n\n- 404 Not Found\n- «Route not found»\n\n### Рішення\n\n> [!CRITICAL]\n> Не вгадуйте шляхи кінцевих точок. Існують лише шляхи зі списку `GET /endpoints`.\n\n1. **Перевірте дійсні кінцеві точки**: `curl https://synapse.schaefer.zone/endpoints`\n2. **Порівняйте URL точно** — чутливий до регістру, без кінцевих слешів\n3. **Перевірте HTTP-метод** — `GET /memory` та `POST /memory` різні\n\n## API-виклики повертають 429\n\n### Симптоми\n\n- 429 Too Many Requests\n- «Rate limit exceeded»\n\n### Рішення\n\n1. **Перейдіть на автентифікацію через заголовок** (без обмеження):\n ```bash\n # Не робіть\n curl \".../memory/recall?key=mk_...\"\n \n # Робіть\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Зачекайте `Retry-After` секунд**, якщо доводиться використовувати `?key=`\n\nДивіться [Обмеження частоти](/docs/api/rate-limits).\n\n## Пошук спогадів не повертає результатів\n\n### Симптоми\n\n- `GET /memory/search?q=...` повертає порожньо\n- Знаєте, що спогади існують\n\n### Рішення\n\n1. **Перевірте, що спогади існують**: `GET /memory/recall`\n2. **Перевірте синтаксис пошуку** — у FTS5 специфічний синтаксис\n3. **Спробуйте простіший запит** — `?q=docker` замість `?q=docker+swarm+deployment`\n4. **Використовуйте семантичний пошук** для концептуальних запитів: `GET /memory/semantic-search?q=...`\n\nДивіться [Пошук FTS5](/docs/concepts/fts5-search).\n\n## Спогади не зберігаються\n\n### Симптоми\n\n- POST /memory повертає успіх\n- GET /memory/recall не показує їх\n\n### Рішення\n\n1. **Перевірте, що той самий Mind Key** — різні ключі = різні mind-и\n2. **Перевірте відповідь** — POST повертає `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Спробуйте GET /memory** (JSON-список) замість /memory/recall (текст)\n4. **Перевірте фільтр** — `?category=` або `?tag=` можуть ховати їх\n\n## Інструменти не з'являються в Claude Desktop\n\n### Симптоми\n\n- Claude Desktop показує 0 інструментів\n- Немає іконки 🔌\n\n### Рішення\n\n1. **Повністю перезапустіть Claude Desktop** (Cmd+Q)\n2. **Перевірте, що файл конфігурації є коректним JSON**\n3. **Перевірте Node.js 18+** встановлено\n4. **Запустіть MCP вручну**: `npx -y synapse-mcp-api@latest`\n5. **Перевірте логи**: `~/Library/Logs/Claude/mcp.log`\n\nДивіться [Усунення несправностей MCP](/docs/mcp/troubleshooting).\n\n## Synapse офлайн\n\n### Симптоми\n\n- Не можна досягти synapse.schaefer.zone\n- curl тайм-аутиться\n\n### Рішення\n\n1. **Перевірте інтернет** — спробуйте інший сайт\n2. **Перевірте стан Synapse**: `curl https://synapse.schaefer.zone/health`\n3. **Зачекайте** — можливо, тимчасовий збій або розгортання\n4. **Перевірте сторінку статусу** (якщо є)\n\nДля self-hosted: перевірте статус Docker-контейнера, підключення до БД.\n\n## Помилки бази даних\n\n### Симптоми\n\n- 500 Internal Server Error\n- «Database connection failed»\n\n### Рішення\n\nДля self-hosted:\n\n1. **Перевірте, що PostgreSQL працює**: `docker ps | grep postgres`\n2. **Перевірте DATABASE_URL** у середовищі\n3. **Перевірте міграції**: `npm run migrate:check`\n4. **Перевірте місце на диску**: `df -h`\n\nДля хостингу: зверніться до підтримки.\n\n## Webhook не спрацьовує\n\n### Симптоми\n\n- Зареєстровано webhook, але не отримуєте зворотних викликів\n- Немає POST на ваш URL\n\n### Рішення\n\n1. **Перевірте, що URL доступний**: `curl -X POST your-url -d '{}'`\n2. **Перевірте фільтр подій** — `memory.*` ловить усі події пам'яті\n3. **Протестуйте webhook**: `POST /webhooks/:id/test`\n4. **Перевірте, що webhook увімкнено**: `GET /webhooks/:id`\n5. **Перевірте SSL** — Synapse потребує дійсний HTTPS для URL webhook-ів\n\nДивіться [Webhooks API](/docs/api/webhooks).\n\n## Cron-завдання не запускається\n\n### Симптоми\n\n- Створено cron-завдання, але воно не спрацьовує\n- `next_run` не оновлюється\n\n### Рішення\n\n1. **Перевірте синтаксис розкладу** — має бути коректний 5-польовий cron АБО ціле число секунд\n2. **Перевірте, що кінцева точка дозволена** — має бути http(s), без приватних IP\n3. **Перевірте, що завдання увімкнено**: `GET /cron`\n4. **Зачекайте на наступний запланований час** — cron не миттєвий\n\nДивіться [Cron та планувальник](/docs/api/cron).\n\n## Потрібна додаткова допомога?\n\n1. **Перевірте наявну документацію**: \n2. **Шукайте в документах**: `GET /docs/search?q=your+question`\n3. **Відкрийте issue**: \n4. **Контакт**: дивіться сторінку `/support`\n\n## Наступні кроки\n\n- [Помилки та обробка помилок](/docs/api/errors)\n- [API FAQ](/docs/faq/api-faq)\n- [Усунення несправностей MCP](/docs/mcp/troubleshooting)\n","content_html":"

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

\n

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

\n

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

\n

Симптоми

\n\n

Рішення

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

Я втратив Mind Key

\n

Симптоми

\n\n

Рішення

\n

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

\n
    \n
  1. Увійти, щоб отримати JWT: POST /login
    2. \n
  2. Вивести список mind-ів: GET /minds (з JWT)
    3. \n
  3. Створити новий mind: POST /minds
    4. \n
  4. Зберегти новий Mind Key
    5. \n
  5. (Опціонально) Видалити старий mind: DELETE /minds/:id
    6. \n
\n

Дані у старому mind-і втрачено, якщо ви не зможете знайти Mind Key.

\n

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

\n

Симптоми

\n\n

Рішення

\n
    \n
  1. Перевірте формат заголовка: Authorization: Bearer mk_...
    2. \n
  2. Перевірте, що Mind Key починається з mk_ (не eyJ, що є JWT)
    3. \n
  3. Протестуйте напряму:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key може бути відкликано — створіть новий mind
    5. \n
\n

Дивіться Автентифікацію.

\n

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

\n

Симптоми

\n\n

Рішення

\n
Не вгадуйте шляхи кінцевих точок. Існують лише шляхи зі списку `GET /endpoints`.
    \n
  1. Перевірте дійсні кінцеві точки: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Порівняйте URL точно — чутливий до регістру, без кінцевих слешів
    3. \n
  3. Перевірте HTTP-метод — GET /memory та POST /memory різні
    4. \n
\n

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

\n

Симптоми

\n\n

Рішення

\n
    \n
  1. Перейдіть на автентифікацію через заголовок (без обмеження):
    # Не робіть\ncurl ".../memory/recall?key=mk_..."\n\n# Робіть\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Зачекайте Retry-After секунд, якщо доводиться використовувати ?key=
    3. \n
\n

Дивіться Обмеження частоти.

\n

Пошук спогадів не повертає результатів

\n

Симптоми

\n\n

Рішення

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

Дивіться Пошук FTS5.

\n

Спогади не зберігаються

\n

Симптоми

\n\n

Рішення

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

Інструменти не з'являються в Claude Desktop

\n

Симптоми

\n\n

Рішення

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

Дивіться Усунення несправностей MCP.

\n

Synapse офлайн

\n

Симптоми

\n\n

Рішення

\n
    \n
  1. Перевірте інтернет — спробуйте інший сайт
    2. \n
  2. Перевірте стан Synapse: curl https://synapse.schaefer.zone/health
    3. \n
  3. Зачекайте — можливо, тимчасовий збій або розгортання
    4. \n
  4. Перевірте сторінку статусу (якщо є)
    5. \n
\n

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

\n

Помилки бази даних

\n

Симптоми

\n\n

Рішення

\n

Для self-hosted:

\n
    \n
  1. Перевірте, що PostgreSQL працює: docker ps | grep postgres
    2. \n
  2. Перевірте DATABASE_URL у середовищі
    3. \n
  3. Перевірте міграції: npm run migrate:check
    4. \n
  4. Перевірте місце на диску: df -h
    5. \n
\n

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

\n

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

\n

Симптоми

\n\n

Рішення

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

Дивіться Webhooks API.

\n

Cron-завдання не запускається

\n

Симптоми

\n\n

Рішення

\n
    \n
  1. Перевірте синтаксис розкладу — має бути коректний 5-польовий cron АБО ціле число секунд
    2. \n
  2. Перевірте, що кінцева точка дозволена — має бути http(s), без приватних IP
    3. \n
  3. Перевірте, що завдання увімкнено: GET /cron
    4. \n
  4. Зачекайте на наступний запланований час — cron не миттєвий
    5. \n
\n

Дивіться Cron та планувальник.

\n

Потрібна додаткова допомога?

\n
    \n
  1. Перевірте наявну документацію: https://synapse.schaefer.zone/docs
    2. \n
  2. Шукайте в документах: GET /docs/search?q=your+question
    3. \n
  3. Відкрийте issue: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. Контакт: дивіться сторінку /support
    5. \n
\n

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

\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"]}