# الأسئلة الشائعة لاستكشاف الأخطاء

حلول لمشكلات Synapse الشائعة.

## لا أستطيع تسجيل الدخول

### الأعراض

- يُرجع `POST /login` 401
- "Invalid email or password"

### الحلول

1. **تحقق أن البريد الإلكتروني صحيح** — حساس لحالة الأحرف
2. **تحقق من كلمة المرور** — 6 أحرف كحد أدنى
3. **سجّل أولًا** إذا لم يكن لديك حساب: `POST /register`
4. **أعد تعيين كلمة المرور** (إذا كان SMTP مُعدًا) عبر واجهة الويب

## فقدت Mind Key

### الأعراض

- لا أستطيع الوصول إلى الذكريات
- حُذف Mind Key أو فُقد

### الحلول

لا يمكن استرداد Mind Keys. يجب أن:

1. تسجّل الدخول للحصول على JWT: `POST /login`
2. تسرد العقول: `GET /minds` (مع JWT)
3. تنشئ عقلًا جديدًا: `POST /minds`
4. تحفظ Mind Key الجديد
5. (اختياري) تحذف العقل القديم: `DELETE /minds/:id`

**البيانات في العقل القديم فقدت** إلا إذا وجدت Mind Key.

## استدعاءات الـ API تُرجع 401

### الأعراض

- جميع استدعاءات الـ API تُرجع 401 Unauthorized
- "Mind Key fehlt oder ungültig"

### الحلول

1. **تحقق من تنسيق الترويسة**: `Authorization: Bearer mk_...`
2. **تحقق أن Mind Key يبدأ بـ `mk_`** (وليس `eyJ` وهو JWT)
3. **اختبر مباشرة**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
4. **قد يكون Mind Key مُبطَلًا** — أنشئ عقلًا جديدًا

راجع [المصادقة](/docs/getting-started/authentication).

## استدعاءات الـ API تُرجع 404

### الأعراض

- 404 Not Found
- "Route not found"

### الحلول

> [!CRITICAL]
> لا تخمّن مسارات نقاط النهاية. فقط المسارات في `GET /endpoints` موجودة.

1. **تحقق من نقاط النهاية الصالحة**: `curl https://synapse.schaefer.zone/endpoints`
2. **قارن عنوان URL بدقة** — حساس لحالة الأحرف، بلا شرطات مائلة لاحقة
3. **تحقق من طريقة HTTP** — `GET /memory` مقابل `POST /memory` مختلفة

## استدعاءات الـ API تُرجع 429

### الأعراض

- 429 Too Many Requests
- "Rate limit exceeded"

### الحلول

1. **بدّل إلى مصادقة الترويسة** (بلا حد معدل):
   ```bash
   # لا تفعل
   curl ".../memory/recall?key=mk_..."
   
   # افعل
   curl -H "Authorization: Bearer mk_..." .../memory/recall
   ```
2. **انتظر `Retry-After` ثانية** إذا وجب استخدام `?key=`

راجع [حدود المعدل](/docs/api/rate-limits).

## بحث الذاكرة يُرجع نتائج فارغة

### الأعراض

- يُرجع `GET /memory/search?q=...` فارغًا
- أعرف أن الذكريات موجودة

### الحلول

1. **تحقق من وجود الذكريات**: `GET /memory/recall`
2. **تحقق من صياغة البحث** — لـ FTS5 صياغة محددة
3. **جرّب استعلامًا أبسط** — `?q=docker` بدلًا من `?q=docker+swarm+deployment`
4. **استخدم البحث الدلالي** للاستعلامات المفاهيمية: `GET /memory/semantic-search?q=...`

راجع [بحث FTS5](/docs/concepts/fts5-search).

## الذكريات لا تستمر

### الأعراض

- يُرجع POST /memory نجاحًا
- لا يُظهرها GET /memory/recall

### الحلول

1. **تحقق من نفس Mind Key** — مفاتيح مختلفة = عقول مختلفة
2. **تحقق من الاستجابة** — يُرجع POST `{ "id": "mem_...", "status": "stored" }`
3. **جرّب GET /memory** (قائمة JSON) بدلًا من /memory/recall (نص)
4. **تحقق من المرشّح** — `?category=` أو `?tag=` قد يخفيها

## الأدوات لا تظهر في Claude Desktop

### الأعراض

- يُظهر Claude Desktop 0 أدوات
- لا توجد أيقونة 🔌

### الحلول

1. **أعد تشغيل Claude Desktop بالكامل** (Cmd+Q)
2. **تحقق أن ملف الإعداد** JSON صالح
3. **تحقق من Node.js 18+** مثبت
4. **شغّل MCP يدويًا**: `npx -y synapse-mcp-api@latest`
5. **تحقق من السجلات**: `~/Library/Logs/Claude/mcp.log`

راجع [استكشاف أخطاء MCP](/docs/mcp/troubleshooting).

## Synapse غير متصل

### الأعراض

- لا يمكن الوصول إلى synapse.schaefer.zone
- curl ينتهي بانتهاء المهلة

### الحلول

1. **تحقق من إنترنتك** — جرّب موقعًا آخر
2. **تحقق من صحة Synapse**: `curl https://synapse.schaefer.zone/health`
3. **انتظر** — قد يكون انقطاعًا مؤقتًا أو نشرًا
4. **تحقق من صفحة الحالة** (إن وُجدت)

للاستضافة الذاتية: تحقق من حالة حاوية Docker، اتصال قاعدة البيانات.

## أخطاء قاعدة البيانات

### الأعراض

- 500 Internal Server Error
- "Database connection failed"

### الحلول

للاستضافة الذاتية:

1. **تحقق من تشغيل PostgreSQL**: `docker ps | grep postgres`
2. **تحقق من DATABASE_URL** في البيئة
3. **تحقق من الترحيلات**: `npm run migrate:check`
4. **تحقق من مساحة القرص**: `df -h`

للمُستضاف: أبلغ الدعم.

## الـ Webhook لا يعمل

### الأعراض

- سجّلت webhook لكن لا أتلقى استدعاءات
- لا POST إلى عنوان URL الخاص بك

### الحلول

1. **تحقق أن عنوان URL قابل للوصول**: `curl -X POST your-url -d '{}'`
2. **تحقق من مرشّح الأحداث** — `memory.*` يطابق جميع أحداث الذاكرة
3. **اختبر الـ webhook**: `POST /webhooks/:id/test`
4. **تحقق أن الـ webhook مُمكَّن**: `GET /webhooks/:id`
5. **تحقق من SSL** — يتطلب Synapse HTTPS صالحًا لعناوين URL للـ webhooks

راجع [Webhooks API](/docs/api/webhooks).

## مهمة Cron لا تعمل

### الأعراض

- أنشأت مهمة cron لكنها لا تعمل
- `next_run` لا يُحدّث

### الحلول

1. **تحقق من صياغة الجدول** — يجب أن تكون cron 5 حقول صالح OR عدد ثوانٍ صحيح
2. **تحقق أن نقطة النهاية مسموحة** — يجب أن تكون http(s)، بلا عناوين IP خاصة
3. **تحقق أن المهمة مُمكَّنة**: `GET /cron`
4. **انتظر الوقت المجدول التالي** — cron ليس فوريًا

راجع [Cron والمجدول](/docs/api/cron).

## تحتاج مزيدًا من المساعدة؟

1. **تحقق من الوثائق الموجودة**: <https://synapse.schaefer.zone/docs>
2. **ابحث في الوثائق**: `GET /docs/search?q=your+question`
3. **افتح issue**: <https://gitlab.com/schaefer-services/synapse/-/issues>
4. **تواصل**: راجع صفحة `/support`

## الخطوات التالية

- [الأخطاء ومعالجتها](/docs/api/errors)
- [أسئلة الـ API الشائعة](/docs/faq/api-faq)
- [استكشاف أخطاء MCP](/docs/mcp/troubleshooting)