{"title":"FAQ Troubleshooting","slug":"troubleshooting","category":"faq","summary":"Solusi untuk masalah Synapse umum — autentikasi, jaringan, data, deployment.","audience":["human","llm"],"tags":["faq","troubleshooting","problems","solutions"],"difficulty":"beginner","updated":"2026-06-27","word_count":615,"read_minutes":3,"lang":"id","translated":true,"requested_lang":"id","content_markdown":"\n# FAQ Troubleshooting\n\nSolusi untuk masalah Synapse umum.\n\n## Saya tidak bisa login\n\n### Gejala\n\n- `POST /login` mengembalikan 401\n- \"Invalid email or password\"\n\n### Solusi\n\n1. **Verifikasi email benar** — case sensitive\n2. **Periksa kata sandi** — minimal 6 karakter\n3. **Daftar dulu** jika Anda tidak punya akun: `POST /register`\n4. **Reset kata sandi** (jika SMTP dikonfigurasi) melalui web UI\n\n## Saya kehilangan Mind Key\n\n### Gejala\n\n- Tidak dapat mengakses memori\n- Mind Key telah dihapus/hilang\n\n### Solusi\n\nMind Key tidak dapat dipulihkan. Anda harus:\n\n1. Login untuk mendapatkan JWT: `POST /login`\n2. Daftar mind: `GET /minds` (dengan JWT)\n3. Buat mind baru: `POST /minds`\n4. Simpan Mind Key baru\n5. (Opsional) Hapus mind lama: `DELETE /minds/:id`\n\n**Data di mind lama hilang** kecuali Anda dapat menemukan Mind Key-nya.\n\n## Panggilan API mengembalikan 401\n\n### Gejala\n\n- Semua panggilan API mengembalikan 401 Unauthorized\n- \"Mind Key fehlt oder ungültig\"\n\n### Solusi\n\n1. **Verifikasi format header**: `Authorization: Bearer mk_...`\n2. **Periksa Mind Key dimulai dengan `mk_`** (bukan `eyJ` yang merupakan JWT)\n3. **Tes langsung**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n4. **Mind Key mungkin dicabut** — buat mind baru\n\nLihat [Autentikasi](/docs/getting-started/authentication).\n\n## Panggilan API mengembalikan 404\n\n### Gejala\n\n- 404 Not Found\n- \"Route not found\"\n\n### Solusi\n\n> [!CRITICAL]\n> Jangan menebak path endpoint. Hanya path di `GET /endpoints` yang ada.\n\n1. **Periksa endpoint valid**: `curl https://synapse.schaefer.zone/endpoints`\n2. **Bandingkan URL persis** — case sensitive, tanpa trailing slash\n3. **Periksa metode HTTP** — `GET /memory` vs `POST /memory` berbeda\n\n## Panggilan API mengembalikan 429\n\n### Gejala\n\n- 429 Too Many Requests\n- \"Rate limit exceeded\"\n\n### Solusi\n\n1. **Beralih ke autentikasi header** (tanpa rate limit):\n ```bash\n # Jangan\n curl \".../memory/recall?key=mk_...\"\n \n # Lakukan\n curl -H \"Authorization: Bearer mk_...\" .../memory/recall\n ```\n2. **Tunggu `Retry-After` detik** jika Anda harus menggunakan `?key=`\n\nLihat [Rate Limits](/docs/api/rate-limits).\n\n## Pencarian memori tidak mengembalikan hasil\n\n### Gejala\n\n- `GET /memory/search?q=...` mengembalikan kosong\n- Tahu memori ada\n\n### Solusi\n\n1. **Verifikasi memori ada**: `GET /memory/recall`\n2. **Periksa sintaks pencarian** — FTS5 memiliki sintaks spesifik\n3. **Coba kueri lebih sederhana** — `?q=docker` alih-alih `?q=docker+swarm+deployment`\n4. **Gunakan pencarian semantik** untuk kueri konseptual: `GET /memory/semantic-search?q=...`\n\nLihat [Pencarian FTS5](/docs/concepts/fts5-search).\n\n## Memori tidak bertahan\n\n### Gejala\n\n- POST /memory mengembalikan sukses\n- GET /memory/recall tidak menampilkannya\n\n### Solusi\n\n1. **Verifikasi Mind Key yang sama** — key berbeda = mind berbeda\n2. **Periksa respons** — POST mengembalikan `{ \"id\": \"mem_...\", \"status\": \"stored\" }`\n3. **Coba GET /memory** (daftar JSON) alih-alih /memory/recall (teks)\n4. **Periksa filter** — `?category=` atau `?tag=` mungkin menyembunyikannya\n\n## Alat tidak muncul di Claude Desktop\n\n### Gejala\n\n- Claude Desktop menunjukkan 0 alat\n- Tidak ada ikon 🔌\n\n### Solusi\n\n1. **Mulai ulang Claude Desktop sepenuhnya** (Cmd+Q)\n2. **Verifikasi file konfigurasi** adalah JSON yang valid\n3. **Periksa Node.js 18+** terpasang\n4. **Jalankan MCP secara manual**: `npx -y synapse-mcp-api@latest`\n5. **Periksa log**: `~/Library/Logs/Claude/mcp.log`\n\nLihat [MCP Troubleshooting](/docs/mcp/troubleshooting).\n\n## Synapse offline\n\n### Gejala\n\n- Tidak dapat mencapai synapse.schaefer.zone\n- curl timeout\n\n### Solusi\n\n1. **Periksa internet Anda** — coba situs lain\n2. **Periksa health Synapse**: `curl https://synapse.schaefer.zone/health`\n3. **Tunggu** — mungkin pemadaman sementara atau deployment\n4. **Periksa halaman status** (jika tersedia)\n\nUntuk self-hosted: periksa status container Docker, koneksi database.\n\n## Error database\n\n### Gejala\n\n- 500 Internal Server Error\n- \"Database connection failed\"\n\n### Solusi\n\nUntuk self-hosted:\n\n1. **Periksa PostgreSQL berjalan**: `docker ps | grep postgres`\n2. **Periksa DATABASE_URL** di env\n3. **Periksa migrasi**: `npm run migrate:check`\n4. **Periksa ruang disk**: `df -h`\n\nUntuk hosted: laporkan ke support.\n\n## Webhook tidak aktif\n\n### Gejala\n\n- Mendaftarkan webhook tetapi tidak menerima callback\n- Tidak ada POST ke URL Anda\n\n### Solusi\n\n1. **Verifikasi URL dapat dijangkau**: `curl -X POST your-url -d '{}'`\n2. **Periksa filter event** — `memory.*` cocok dengan semua event memori\n3. **Tes webhook**: `POST /webhooks/:id/test`\n4. **Periksa webhook diaktifkan**: `GET /webhooks/:id`\n5. **Verifikasi SSL** — Synapse memerlukan HTTPS yang valid untuk URL webhook\n\nLihat [Webhooks API](/docs/api/webhooks).\n\n## Cron job tidak berjalan\n\n### Gejala\n\n- Membuat cron job tetapi tidak aktif\n- `next_run` tidak diperbarui\n\n### Solusi\n\n1. **Periksa sintaks jadwal** — harus cron 5-field yang valid ATAU detik bilangan bulat\n2. **Verifikasi endpoint diizinkan** — harus http(s), tanpa IP privat\n3. **Periksa job diaktifkan**: `GET /cron`\n4. **Tunggu waktu terjadwal berikutnya** — cron tidak instan\n\nLihat [Cron & Scheduler](/docs/api/cron).\n\n## Butuh Bantuan Lebih Lanjut?\n\n1. **Periksa dokumentasi yang ada**: \n2. **Cari dokumentasi**: `GET /docs/search?q=your+question`\n3. **Buka issue**: \n4. **Kontak**: lihat halaman `/support`\n\n## Langkah Berikutnya\n\n- [Errors & Error Handling](/docs/api/errors)\n- [FAQ API](/docs/faq/api-faq)\n- [MCP Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

FAQ Troubleshooting

\n

Solusi untuk masalah Synapse umum.

\n

Saya tidak bisa login

\n

Gejala

\n\n

Solusi

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

Saya kehilangan Mind Key

\n

Gejala

\n\n

Solusi

\n

Mind Key tidak dapat dipulihkan. Anda harus:

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

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

\n

Panggilan API mengembalikan 401

\n

Gejala

\n\n

Solusi

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

Lihat Autentikasi.

\n

Panggilan API mengembalikan 404

\n

Gejala

\n\n

Solusi

\n
Jangan menebak path endpoint. Hanya path di `GET /endpoints` yang ada.
    \n
  1. Periksa endpoint valid: curl https://synapse.schaefer.zone/endpoints
    2. \n
  2. Bandingkan URL persis — case sensitive, tanpa trailing slash
    3. \n
  3. Periksa metode HTTP — GET /memory vs POST /memory berbeda
    4. \n
\n

Panggilan API mengembalikan 429

\n

Gejala

\n\n

Solusi

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

Lihat Rate Limits.

\n

Pencarian memori tidak mengembalikan hasil

\n

Gejala

\n\n

Solusi

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

Lihat Pencarian FTS5.

\n

Memori tidak bertahan

\n

Gejala

\n\n

Solusi

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

Alat tidak muncul di Claude Desktop

\n

Gejala

\n\n

Solusi

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

Lihat MCP Troubleshooting.

\n

Synapse offline

\n

Gejala

\n\n

Solusi

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

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

\n

Error database

\n

Gejala

\n\n

Solusi

\n

Untuk self-hosted:

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

Untuk hosted: laporkan ke support.

\n

Webhook tidak aktif

\n

Gejala

\n\n

Solusi

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

Lihat Webhooks API.

\n

Cron job tidak berjalan

\n

Gejala

\n\n

Solusi

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

Lihat Cron & Scheduler.

\n

Butuh Bantuan Lebih Lanjut?

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

Langkah Berikutnya

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