{"title":"FAQ — rozwiązywanie problemów","slug":"troubleshooting","category":"faq","summary":"Rozwiązania częstych problemów Synapse — autoryzacja, sieć, dane, wdrożenie.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":647,"read_minutes":3,"lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# FAQ — rozwiązywanie problemów\n\nRozwiązania częstych problemów Synapse.\n\n## Nie mogę się zalogować\n\n### Symptomy\n\n- `POST /login` zwraca 401\n- „Invalid email or password\"\n\n### Rozwiązania\n\n1. **Zweryfikować poprawność e-maila** — wielkość liter ma znaczenie\n2. **Sprawdzić hasło** — minimum 6 znaków\n3. **Najpierw zarejestrować**, jeśli nie ma konta: `POST /register`\n4. **Zresetować hasło** (jeśli skonfigurowano SMTP) przez interfejs WWW\n\n## Zgubiłem Mind Key\n\n### Symptomy\n\n- Brak dostępu do wspomnień\n- Mind Key został usunięty/zgubiony\n\n### Rozwiązania\n\nMind Key nie można odzyskać. Należy:\n\n1. Zalogować się, aby uzyskać JWT: `POST /login`\n2. Wylistować umysły: `GET /minds` (z JWT)\n3. Utworzyć nowy umysł: `POST /minds`\n4. Zapisać nowy Mind Key\n5. (Opcjonalnie) Usunąć stary umysł: `DELETE /minds/:id`\n\n**Dane w starym umyśle są utracone**, chyba że Mind Key zostanie odnaleziony.\n\n## Wywołania API zwracają 401\n\n### Symptomy\n\n- Wszystkie wywołania API zwracają 401 Unauthorized\n- „Mind Key fehlt oder ungültig\"\n\n### Rozwiązania\n\n1. **Zweryfikować format nagłówka**: `Authorization: Bearer mk_...`\n2. **Sprawdzić, czy Mind Key zaczyna się od `mk_`** (nie `eyJ`, które to JWT)\n3. **Przetestować bezpośrednio**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key może być cofnięty** — utworzyć nowy umysł\n\nPatrz [Autoryzacja](/docs/getting-started/authentication).\n\n## Wywołania API zwracają 404\n\n### Symptomy\n\n- 404 Not Found\n- „Route not found\"\n\n### Rozwiązania\n\n> [!CRITICAL]\n> Nie wolno zgadywać ścieżek endpointów. Istnieją tylko ścieżki w `GET /endpoints`.\n\n1. **Sprawdzić poprawne endpointy**: `curl https://synapse.schaefer.zone/endpoints`\n2. **Porównać URL dokładnie** — wielkość liter ma znaczenie, bez końcowych ukośników\n3. **Sprawdzić metodę HTTP** — `GET /memory` i `POST /memory` to różne endpointy\n\n## Wywołania API zwracają 429\n\n### Symptomy\n\n- 429 Too Many Requests\n- „Rate limit exceeded\"\n\n### Rozwiązania\n\n1. **Przełączyć się na autoryzację nagłówkiem** (bez limitu):\n ```bash\n # Nie\n curl \".../memory/recall?key=mk_...\"\n \n # Tak\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Odczekać `Retry-After` sekund**, jeśli trzeba użyć `?key=`\n\nPatrz [Limity żądań](/docs/api/rate-limits).\n\n## Wyszukiwanie wspomnień nie zwraca wyników\n\n### Symptomy\n\n- `GET /memory/search?q=...` zwraca puste\n- Wspomnienia na pewno istnieją\n\n### Rozwiązania\n\n1. **Zweryfikować istnienie wspomnień**: `GET /memory/recall`\n2. **Sprawdzić składnię wyszukiwania** — FTS5 ma specyficzną składnię\n3. **Spróbować prostszego zapytania** — `?q=docker` zamiast `?q=docker+swarm+deployment`\n4. **Użyć wyszukiwania semantycznego** do zapytań koncepcyjnych: `GET /memory/semantic-search?q=...`\n\nPatrz [Wyszukiwanie FTS5](/docs/concepts/fts5-search).\n\n## Wspomnienia nie utrwalają się\n\n### Symptomy\n\n- POST /memory zwraca sukces\n- GET /memory/recall nie pokazuje ich\n\n### Rozwiązania\n\n1. **Zweryfikować ten sam Mind Key** — różne klucze = różne umysły\n2. **Sprawdzić odpowiedź** — POST zwraca `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Spróbować GET /memory** (lista JSON) zamiast /memory/recall (tekst)\n4. **Sprawdzić filtr** — `?category=` lub `?tag=` mogą je ukrywać\n\n## Narzędzia nie pojawiają się w Claude Desktop\n\n### Symptomy\n\n- Claude Desktop pokazuje 0 narzędzi\n- Brak ikony 🔌\n\n### Rozwiązania\n\n1. **W pełni zrestartować Claude Desktop** (Cmd+Q)\n2. **Zweryfikować, czy plik konfiguracyjny** jest poprawnym JSON-em\n3. **Sprawdzić Node.js 18+** zainstalowany\n4. **Uruchomić MCP ręcznie**: `npx -y synapse-mcp-api@latest`\n5. **Sprawdzić logi**: `~/Library/Logs/Claude/mcp.log`\n\nPatrz [Rozwiązywanie problemów MCP](/docs/mcp/troubleshooting).\n\n## Synapse jest offline\n\n### Symptomy\n\n- Nie można dotrzeć do synapse.schaefer.zone\n- curl przekracza czas oczekiwania\n\n### Rozwiązania\n\n1. **Sprawdzić połączenie internetowe** — spróbować innej strony\n2. **Sprawdzić kondycję Synapse**: `curl https://synapse.schaefer.zone/health`\n3. **Poczekać** — może to być tymczasowa awaria lub wdrożenie\n4. **Sprawdzić stronę statusu** (jeśli dostępna)\n\nDla self-hosted: sprawdzić status kontenera Docker, połączenie z bazą danych.\n\n## Błędy bazy danych\n\n### Symptomy\n\n- 500 Internal Server Error\n- „Database connection failed\"\n\n### Rozwiązania\n\nDla self-hosted:\n\n1. **Sprawdzić, czy PostgreSQL działa**: `docker ps | grep postgres`\n2. **Sprawdzić DATABASE_URL** w środowisku\n3. **Sprawdzić migracje**: `npm run migrate:check`\n4. **Sprawdzić miejsce na dysku**: `df -h`\n\nDla hostowanej wersji: zgłosić do wsparcia.\n\n## Webhook się nie wyzwala\n\n### Symptomy\n\n- Zarejestrowany webhook, ale brak wywołań zwrotnych\n- Brak POST pod podany URL\n\n### Rozwiązania\n\n1. **Zweryfikować osiągalność URL**: `curl -X POST your-url -d '{}'`\n2. **Sprawdzić filtr zdarzeń** — `memory.*` pasuje do wszystkich zdarzeń pamięci\n3. **Przetestować webhook**: `POST /webhooks/:id/test`\n4. **Sprawdzić, czy webhook jest włączony**: `GET /webhooks/:id`\n5. **Zweryfikować SSL** — Synapse wymaga ważnego HTTPS dla URL-i webhooków\n\nPatrz [Webhooks API](/docs/api/webhooks).\n\n## Zadanie cron się nie uruchamia\n\n### Symptomy\n\n- Utworzono zadanie cron, ale się nie wyzwala\n- `next_run` się nie aktualizuje\n\n### Rozwiązania\n\n1. **Sprawdzić składnię harmonogramu** — musi być poprawny cron 5-polowy lub liczba całkowita sekund\n2. **Zweryfikować, czy endpoint jest dozwolony** — musi być http(s), bez prywatnych IP\n3. **Sprawdzić, czy zadanie jest włączone**: `GET /cron`\n4. **Poczekać na następny zaplanowany czas** — cron nie jest natychmiastowy\n\nPatrz [Cron i Scheduler](/docs/api/cron).\n\n## Potrzebna dalsza pomoc?\n\n1. **Sprawdzić istniejącą dokumentację**: \n2. **Przeszukać dokumentację**: `GET /docs/search?q=your+question`\n3. **Otworzyć zgłoszenie**: \n4. **Kontakt**: patrz strona `/support`\n\n## Następne kroki\n\n- [Błędy i ich obsługa](/docs/api/errors)\n- [FAQ API](/docs/faq/api-faq)\n- [Rozwiązywanie problemów MCP](/docs/mcp/troubleshooting)\n","content_html":"

FAQ — rozwiązywanie problemów

\n

Rozwiązania częstych problemów Synapse.

\n

Nie mogę się zalogować

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Zweryfikować poprawność e-maila — wielkość liter ma znaczenie
    2. \n
  2. Sprawdzić hasło — minimum 6 znaków
    3. \n
  3. Najpierw zarejestrować, jeśli nie ma konta: POST /register
    4. \n
  4. Zresetować hasło (jeśli skonfigurowano SMTP) przez interfejs WWW
    5. \n
\n

Zgubiłem Mind Key

\n

Symptomy

\n\n

Rozwiązania

\n

Mind Key nie można odzyskać. Należy:

\n
    \n
  1. Zalogować się, aby uzyskać JWT: POST /login
    2. \n
  2. Wylistować umysły: GET /minds (z JWT)
    3. \n
  3. Utworzyć nowy umysł: POST /minds
    4. \n
  4. Zapisać nowy Mind Key
    5. \n
  5. (Opcjonalnie) Usunąć stary umysł: DELETE /minds/:id
    6. \n
\n

Dane w starym umyśle są utracone, chyba że Mind Key zostanie odnaleziony.

\n

Wywołania API zwracają 401

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Zweryfikować format nagłówka: Authorization: Bearer mk_...
    2. \n
  2. Sprawdzić, czy Mind Key zaczyna się od mk_ (nie eyJ, które to JWT)
    3. \n
  3. Przetestować bezpośrednio:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    4. \n
  4. Mind Key może być cofnięty — utworzyć nowy umysł
    5. \n
\n

Patrz Autoryzacja.

\n

Wywołania API zwracają 404

\n

Symptomy

\n\n

Rozwiązania

\n
Nie wolno zgadywać ścieżek endpointów. Istnieją tylko ścieżki w `GET /endpoints`.
    \n
  1. Sprawdzić poprawne endpointy: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Porównać URL dokładnie — wielkość liter ma znaczenie, bez końcowych ukośników
    3. \n
  3. Sprawdzić metodę HTTP — GET /memory i POST /memory to różne endpointy
    4. \n
\n

Wywołania API zwracają 429

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Przełączyć się na autoryzację nagłówkiem (bez limitu):
    # Nie\ncurl ".../memory/recall?key=mk_..."\n\n# Tak\ncurl -H "Authorization: Bearer mk_..." .../memory/recall
    2. \n
  2. Odczekać Retry-After sekund, jeśli trzeba użyć ?key=
    3. \n
\n

Patrz Limity żądań.

\n

Wyszukiwanie wspomnień nie zwraca wyników

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Zweryfikować istnienie wspomnień: GET /memory/recall
    2. \n
  2. Sprawdzić składnię wyszukiwania — FTS5 ma specyficzną składnię
    3. \n
  3. Spróbować prostszego zapytania — ?q=docker zamiast ?q=docker+swarm+deployment
    4. \n
  4. Użyć wyszukiwania semantycznego do zapytań koncepcyjnych: GET /memory/semantic-search?q=...
    5. \n
\n

Patrz Wyszukiwanie FTS5.

\n

Wspomnienia nie utrwalają się

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Zweryfikować ten sam Mind Key — różne klucze = różne umysły
    2. \n
  2. Sprawdzić odpowiedź — POST zwraca { "id": "mem_...", "status": "stored" }
    3. \n
  3. Spróbować GET /memory (lista JSON) zamiast /memory/recall (tekst)
    4. \n
  4. Sprawdzić filtr — ?category= lub ?tag= mogą je ukrywać
    5. \n
\n

Narzędzia nie pojawiają się w Claude Desktop

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. W pełni zrestartować Claude Desktop (Cmd+Q)
    2. \n
  2. Zweryfikować, czy plik konfiguracyjny jest poprawnym JSON-em
    3. \n
  3. Sprawdzić Node.js 18+ zainstalowany
    4. \n
  4. Uruchomić MCP ręcznie: npx -y synapse-mcp-api@latest
    5. \n
  5. Sprawdzić logi: ~/Library/Logs/Claude/mcp.log
    6. \n
\n

Patrz Rozwiązywanie problemów MCP.

\n

Synapse jest offline

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Sprawdzić połączenie internetowe — spróbować innej strony
    2. \n
  2. Sprawdzić kondycję Synapse: curl https://synapse.schaefer.zone/health
    3. \n
  3. Poczekać — może to być tymczasowa awaria lub wdrożenie
    4. \n
  4. Sprawdzić stronę statusu (jeśli dostępna)
    5. \n
\n

Dla self-hosted: sprawdzić status kontenera Docker, połączenie z bazą danych.

\n

Błędy bazy danych

\n

Symptomy

\n\n

Rozwiązania

\n

Dla self-hosted:

\n
    \n
  1. Sprawdzić, czy PostgreSQL działa: docker ps | grep postgres
    2. \n
  2. Sprawdzić DATABASE_URL w środowisku
    3. \n
  3. Sprawdzić migracje: npm run migrate:check
    4. \n
  4. Sprawdzić miejsce na dysku: df -h
    5. \n
\n

Dla hostowanej wersji: zgłosić do wsparcia.

\n

Webhook się nie wyzwala

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Zweryfikować osiągalność URL: curl -X POST your-url -d '{}'
    2. \n
  2. Sprawdzić filtr zdarzeń — memory.* pasuje do wszystkich zdarzeń pamięci
    3. \n
  3. Przetestować webhook: POST /webhooks/:id/test
    4. \n
  4. Sprawdzić, czy webhook jest włączony: GET /webhooks/:id
    5. \n
  5. Zweryfikować SSL — Synapse wymaga ważnego HTTPS dla URL-i webhooków
    6. \n
\n

Patrz Webhooks API.

\n

Zadanie cron się nie uruchamia

\n

Symptomy

\n\n

Rozwiązania

\n
    \n
  1. Sprawdzić składnię harmonogramu — musi być poprawny cron 5-polowy lub liczba całkowita sekund
    2. \n
  2. Zweryfikować, czy endpoint jest dozwolony — musi być http(s), bez prywatnych IP
    3. \n
  3. Sprawdzić, czy zadanie jest włączone: GET /cron
    4. \n
  4. Poczekać na następny zaplanowany czas — cron nie jest natychmiastowy
    5. \n
\n

Patrz Cron i Scheduler.

\n

Potrzebna dalsza pomoc?

\n
    \n
  1. Sprawdzić istniejącą dokumentację: https://synapse.schaefer.zone/docs
    2. \n
  2. Przeszukać dokumentację: GET /docs/search?q=your+question
    3. \n
  3. Otworzyć zgłoszenie: https://gitlab.com/schaefer-services/synapse/-/issues
    4. \n
  4. Kontakt: patrz strona /support
    5. \n
\n

Następne kroki

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