Sorun Giderme SSS

Yaygın Synapse sorunlarına çözümler.

Giriş yapamıyorum

Belirtiler

• POST /login 401 döndürüyor
• "Invalid email or password"

Çözümler

1. E-postanın doğru olduğunu doğrulayın — büyük/küçük harf duyarlı
2. Parolayı kontrol edin — en az 6 karakter
3. Hesabınız yoksa önce kaydolun: POST /register
4. (SMTP yapılandırılmışsa) web arayüzü üzerinden parola sıfırlayın

Mind Key'imi kaybettim

Belirtiler

• Belleklere erilemiyor
• Mind Key silinmiş/kaybolmuş

Çözümler

Mind Key'ler kurtarılamaz. Şunları yapmalısınız:

1. JWT almak için giriş: POST /login
2. Mind'leri listele: GET /minds (JWT ile)
3. Yeni mind oluştur: POST /minds
4. Yeni Mind Key'i kaydet
5. (İsteğe bağlı) Eski mind'i sil: DELETE /minds/:id

Eski mind'deki veriler Mind Key'i bulamadıkça kaybedilir.

API çağrıları 401 döndürüyor

Belirtiler

• Tüm API çağrıları 401 Unauthorized döndürüyor
• "Mind Key fehlt oder ungültig"

Çözümler

1. Başlık biçimini doğrulayın: Authorization: Bearer mk_...
2. Mind Key'in mk_ ile başladığını kontrol edin (JWT olan eyJ değil)
3. Doğrudan test edin:

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

4. Mind Key iptal edilmiş olabilir — yeni bir mind oluşturun

Bkz. Kimlik Doğrulama.

API çağrıları 404 döndürüyor

Belirtiler

• 404 Not Found
• "Route not found"

Çözümler

1. Geçerli uç noktaları kontrol edin: curl https://synapse.schaefer.zone/endpoints
2. URL'yi tam olarak karşılaştırın — büyük/küçük harf duyarlı, sondaki eğik çizgi yok
3. HTTP yöntemini kontrol edin — GET /memory ve POST /memory farklıdır

API çağrıları 429 döndürüyor

Belirtiler

• 429 Too Many Requests
• "Rate limit exceeded"

Çözümler

1. Header kimlik doğrulamasına geçin (hız sınırı yok):

   # Don't
   curl ".../memory/recall?key=mk_..."
   
   # Do
   curl -H "Authorization: Bearer mk_..." .../memory/recall

2. ?key= kullanmanız gerekiyorsa Retry-After saniye bekleyin

Bkz. Hız Sınırları.

Bellek arama sonuç döndürmüyor

Belirtiler

• GET /memory/search?q=... boş döndürüyor
• Belleklerin var olduğunu biliyorsunuz

Çözümler

1. Belleklerin var olduğunu doğrulayın: GET /memory/recall
2. Arama sözdizimini kontrol edin — FTS5'ün özel sözdizimi var
3. Daha basit sorgu deneyin — ?q=docker+swarm+deployment yerine ?q=docker
4. Kavramsal sorgular için anlamsal arama kullanın: GET /memory/semantic-search?q=...

Bkz. FTS5 Arama.

Bellekler kalıcı olmuyor

Belirtiler

• POST /memory başarı döndürüyor
• GET /memory/recall bunları göstermiyor

Çözümler

1. Aynı Mind Key'i doğrulayın — farklı anahtarlar = farklı mind'ler
2. Yanıtı kontrol edin — POST { "id": "mem_...", "status": "stored" } döndürür
3. /memory/recall (metin) yerine GET /memory (JSON listesi) deneyin
4. Filtreyi kontrol edin — ?category= veya ?tag= onları gizliyor olabilir

Araçlar Claude Desktop'da görünmüyor

Belirtiler

• Claude Desktop 0 araç gösteriyor
• 🔌 simgesi yok

Çözümler

1. Claude Desktop'ı tamamen yeniden başlatın (Cmd+Q)
2. Yapılandırma dosyasının geçerli JSON olduğunu doğrulayın
3. Node.js 18+ kurulu olduğunu kontrol edin
4. MCP'yi manuel çalıştırın: npx -y synapse-mcp-api@latest
5. Logları kontrol edin: ~/Library/Logs/Claude/mcp.log

Bkz. MCP Sorun Giderme.

Synapse çevrimdışı

Belirtiler

• synapse.schaefer.zone'a ulaşılamıyor
• curl zaman aşımına uğruyor

Çözümler

1. İnternetinizi kontrol edin — başka bir site deneyin
2. Synapse sağlığını kontrol edin: curl https://synapse.schaefer.zone/health
3. Bekleyin — geçici kesinti veya dağıtım olabilir
4. Durum sayfasını kontrol edin (varsa)

Self-hosted için: Docker konteyner durumunu, veritabanı bağlantısını kontrol edin.

Veritabanı hataları

Belirtiler

• 500 Internal Server Error
• "Database connection failed"

Çözümler

Self-hosted için:

1. PostgreSQL'in çalıştığını kontrol edin: docker ps | grep postgres
2. Env'de DATABASE_URL'i kontrol edin
3. Migrasyonları kontrol edin: npm run migrate:check
4. Disk alanını kontrol edin: df -h

Barındırılan için: desteğe bildirin.

Webhook tetiklenmiyor

Belirtiler

• Webhook kaydedildi ama geri arama alınmıyor
• URL'nize POST yok

Çözümler

1. URL'nin erişilebilir olduğunu doğrulayın: curl -X POST your-url -d '{}'
2. Olay filtresini kontrol edin — memory.* tüm bellek olaylarını eşleştirir
3. Webhook'u test edin: POST /webhooks/:id/test
4. Webhook'un etkin olduğunu kontrol edin: GET /webhooks/:id
5. SSL'i doğrulayın — Synapse webhook URL'leri için geçerli HTTPS gerektirir

Bkz. Webhooks API.

Cron işi çalışmıyor

Belirtiler

• Cron işi oluşturuldu ama tetiklenmiyor
• next_run güncellenmiyor

Çözümler

1. Zamanlama sözdizimini kontrol edin — geçerli 5 alanlı cron veya tamsayı saniye olmalı
2. Uç noktanın izin verildiğini doğrulayın — http(s) olmalı, özel IP yok
3. İşin etkin olduğunu kontrol edin: GET /cron
4. Sonraki zamanlanmış saati bekleyin — cron anında değil

Bkz. Cron & Zamanlayıcı.

Daha Fazla Yardıma mı İhtiyacınız Var?

1. Mevcut docs'ları kontrol edin: https://synapse.schaefer.zone/docs
2. Docs'larda arama: GET /docs/search?q=your+question
3. Issue açın: https://gitlab.com/schaefer-services/synapse/-/issues
4. İletişim: /support sayfasına bakın

Sonraki Adımlar

• Hatalar & Hata Yönetimi
• API SSS
• MCP Sorun Giderme