# FAQ Troubleshooting

Solusi untuk masalah Synapse umum.

## Saya tidak bisa login

### Gejala

- `POST /login` mengembalikan 401
- "Invalid email or password"

### Solusi

1. **Verifikasi email benar** — case sensitive
2. **Periksa kata sandi** — minimal 6 karakter
3. **Daftar dulu** jika Anda tidak punya akun: `POST /register`
4. **Reset kata sandi** (jika SMTP dikonfigurasi) melalui web UI

## Saya kehilangan Mind Key

### Gejala

- Tidak dapat mengakses memori
- Mind Key telah dihapus/hilang

### Solusi

Mind Key tidak dapat dipulihkan. Anda harus:

1. Login untuk mendapatkan JWT: `POST /login`
2. Daftar mind: `GET /minds` (dengan JWT)
3. Buat mind baru: `POST /minds`
4. Simpan Mind Key baru
5. (Opsional) Hapus mind lama: `DELETE /minds/:id`

**Data di mind lama hilang** kecuali Anda dapat menemukan Mind Key-nya.

## Panggilan API mengembalikan 401

### Gejala

- Semua panggilan API mengembalikan 401 Unauthorized
- "Mind Key fehlt oder ungültig"

### Solusi

1. **Verifikasi format header**: `Authorization: Bearer mk_...`
2. **Periksa Mind Key dimulai dengan `mk_`** (bukan `eyJ` yang merupakan JWT)
3. **Tes langsung**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **Mind Key mungkin dicabut** — buat mind baru

Lihat [Autentikasi](/docs/getting-started/authentication).

## Panggilan API mengembalikan 404

### Gejala

- 404 Not Found
- "Route not found"

### Solusi

> [!CRITICAL]
> Jangan menebak path endpoint. Hanya path di `GET /endpoints` yang ada.

1. **Periksa endpoint valid**: `curl https://synapse.schaefer.zone/endpoints`
2. **Bandingkan URL persis** — case sensitive, tanpa trailing slash
3. **Periksa metode HTTP** — `GET /memory` vs `POST /memory` berbeda

## Panggilan API mengembalikan 429

### Gejala

- 429 Too Many Requests
- "Rate limit exceeded"

### Solusi

1. **Beralih ke autentikasi header** (tanpa rate limit):
   ```bash
   # Jangan
   curl ".../memory/recall?key=mk_..."
   
   # Lakukan
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **Tunggu `Retry-After` detik** jika Anda harus menggunakan `?key=`

Lihat [Rate Limits](/docs/api/rate-limits).

## Pencarian memori tidak mengembalikan hasil

### Gejala

- `GET /memory/search?q=...` mengembalikan kosong
- Tahu memori ada

### Solusi

1. **Verifikasi memori ada**: `GET /memory/recall`
2. **Periksa sintaks pencarian** — FTS5 memiliki sintaks spesifik
3. **Coba kueri lebih sederhana** — `?q=docker` alih-alih `?q=docker+swarm+deployment`
4. **Gunakan pencarian semantik** untuk kueri konseptual: `GET /memory/semantic-search?q=...`

Lihat [Pencarian FTS5](/docs/concepts/fts5-search).

## Memori tidak bertahan

### Gejala

- POST /memory mengembalikan sukses
- GET /memory/recall tidak menampilkannya

### Solusi

1. **Verifikasi Mind Key yang sama** — key berbeda = mind berbeda
2. **Periksa respons** — POST mengembalikan `{ "id": "mem_...", "status": "stored" }`
3. **Coba GET /memory** (daftar JSON) alih-alih /memory/recall (teks)
4. **Periksa filter** — `?category=` atau `?tag=` mungkin menyembunyikannya

## Alat tidak muncul di Claude Desktop

### Gejala

- Claude Desktop menunjukkan 0 alat
- Tidak ada ikon 🔌

### Solusi

1. **Mulai ulang Claude Desktop sepenuhnya** (Cmd+Q)
2. **Verifikasi file konfigurasi** adalah JSON yang valid
3. **Periksa Node.js 18+** terpasang
4. **Jalankan MCP secara manual**: `npx -y synapse-mcp-api@latest`
5. **Periksa log**: `~/Library/Logs/Claude/mcp.log`

Lihat [MCP Troubleshooting](/docs/mcp/troubleshooting).

## Synapse offline

### Gejala

- Tidak dapat mencapai synapse.schaefer.zone
- curl timeout

### Solusi

1. **Periksa internet Anda** — coba situs lain
2. **Periksa health Synapse**: `curl https://synapse.schaefer.zone/health`
3. **Tunggu** — mungkin pemadaman sementara atau deployment
4. **Periksa halaman status** (jika tersedia)

Untuk self-hosted: periksa status container Docker, koneksi database.

## Error database

### Gejala

- 500 Internal Server Error
- "Database connection failed"

### Solusi

Untuk self-hosted:

1. **Periksa PostgreSQL berjalan**: `docker ps | grep postgres`
2. **Periksa DATABASE_URL** di env
3. **Periksa migrasi**: `npm run migrate:check`
4. **Periksa ruang disk**: `df -h`

Untuk hosted: laporkan ke support.

## Webhook tidak aktif

### Gejala

- Mendaftarkan webhook tetapi tidak menerima callback
- Tidak ada POST ke URL Anda

### Solusi

1. **Verifikasi URL dapat dijangkau**: `curl -X POST your-url -d '{}'`
2. **Periksa filter event** — `memory.*` cocok dengan semua event memori
3. **Tes webhook**: `POST /webhooks/:id/test`
4. **Periksa webhook diaktifkan**: `GET /webhooks/:id`
5. **Verifikasi SSL** — Synapse memerlukan HTTPS yang valid untuk URL webhook

Lihat [Webhooks API](/docs/api/webhooks).

## Cron job tidak berjalan

### Gejala

- Membuat cron job tetapi tidak aktif
- `next_run` tidak diperbarui

### Solusi

1. **Periksa sintaks jadwal** — harus cron 5-field yang valid ATAU detik bilangan bulat
2. **Verifikasi endpoint diizinkan** — harus http(s), tanpa IP privat
3. **Periksa job diaktifkan**: `GET /cron`
4. **Tunggu waktu terjadwal berikutnya** — cron tidak instan

Lihat [Cron & Scheduler](/docs/api/cron).

## Butuh Bantuan Lebih Lanjut?

1. **Periksa dokumentasi yang ada**: <https://synapse.schaefer.zone/docs>
2. **Cari dokumentasi**: `GET /docs/search?q=your+question`
3. **Buka issue**: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. **Kontak**: lihat halaman `/support`

## Langkah Berikutnya

- [Errors & Error Handling](/docs/api/errors)
- [FAQ API](/docs/faq/api-faq)
- [MCP Troubleshooting](/docs/mcp/troubleshooting)