# 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**:
   ```bash
   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](/docs/getting-started/authentication).

## Wywołania API zwracają 404

### Symptomy

- 404 Not Found
- „Route not found"

### Rozwiązania

> [!CRITICAL]
> Nie wolno zgadywać ścieżek endpointów. Istnieją tylko ścieżki w `GET /endpoints`.

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):
   ```bash
   # 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ń](/docs/api/rate-limits).

## 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](/docs/concepts/fts5-search).

## 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](/docs/mcp/troubleshooting).

## 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](/docs/api/webhooks).

## 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](/docs/api/cron).

## 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](/docs/api/errors)
- [FAQ API](/docs/faq/api-faq)
- [Rozwiązywanie problemów MCP](/docs/mcp/troubleshooting)