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:

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

4. Mind Key mungkin dicabut — buat mind baru

Lihat Autentikasi.

Panggilan API mengembalikan 404

Gejala

• 404 Not Found
• "Route not found"

Solusi

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):

   # 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.

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.

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.

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.

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.

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
• FAQ API
• MCP Troubleshooting