FAQ — rozwiązywanie problemów

Rozwiązania częstych problemów Synapse.

Nie mogę się zalogować

Symptomy

• POST /login zwraca 401
• „Invalid email or password"

Rozwiązania

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

Zgubiłem Mind Key

Symptomy

• Brak dostępu do wspomnień
• Mind Key został usunięty/zgubiony

Rozwiązania

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

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

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

Wywołania API zwracają 401

Symptomy

• Wszystkie wywołania API zwracają 401 Unauthorized
• „Mind Key fehlt oder ungültig"

Rozwiązania

1. Zweryfikować format nagłówka: Authorization: Bearer mk_...
2. Sprawdzić, czy Mind Key zaczyna się od mk_ (nie eyJ, które to JWT)
3. Przetestować bezpośrednio:

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

4. Mind Key może być cofnięty — utworzyć nowy umysł

Patrz Autoryzacja.

Wywołania API zwracają 404

Symptomy

• 404 Not Found
• „Route not found"

Rozwiązania

1. Sprawdzić poprawne endpointy: curl https://synapse.schaefer.zone/endpoints
2. Porównać URL dokładnie — wielkość liter ma znaczenie, bez końcowych ukośników
3. Sprawdzić metodę HTTP — GET /memory i POST /memory to różne endpointy

Wywołania API zwracają 429

Symptomy

• 429 Too Many Requests
• „Rate limit exceeded"

Rozwiązania

1. Przełączyć się na autoryzację nagłówkiem (bez limitu):

   # Nie
   curl ".../memory/recall?key=mk_..."
   
   # Tak
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. Odczekać Retry-After sekund, jeśli trzeba użyć ?key=

Patrz Limity żądań.

Wyszukiwanie wspomnień nie zwraca wyników

Symptomy

• GET /memory/search?q=... zwraca puste
• Wspomnienia na pewno istnieją

Rozwiązania

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

Patrz Wyszukiwanie FTS5.

Wspomnienia nie utrwalają się

Symptomy

• POST /memory zwraca sukces
• GET /memory/recall nie pokazuje ich

Rozwiązania

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

Narzędzia nie pojawiają się w Claude Desktop

Symptomy

• Claude Desktop pokazuje 0 narzędzi
• Brak ikony 🔌

Rozwiązania

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

Patrz Rozwiązywanie problemów MCP.

Synapse jest offline

Symptomy

• Nie można dotrzeć do synapse.schaefer.zone
• curl przekracza czas oczekiwania

Rozwiązania

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

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

Błędy bazy danych

Symptomy

• 500 Internal Server Error
• „Database connection failed"

Rozwiązania

Dla self-hosted:

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

Dla hostowanej wersji: zgłosić do wsparcia.

Webhook się nie wyzwala

Symptomy

• Zarejestrowany webhook, ale brak wywołań zwrotnych
• Brak POST pod podany URL

Rozwiązania

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

Patrz Webhooks API.

Zadanie cron się nie uruchamia

Symptomy

• Utworzono zadanie cron, ale się nie wyzwala
• next_run się nie aktualizuje

Rozwiązania

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

Patrz Cron i Scheduler.

Potrzebna dalsza pomoc?

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

Następne kroki

• Błędy i ich obsługa
• FAQ API
• Rozwiązywanie problemów MCP