# معالجة الأخطاء والتعافي منها (/ar/docs/verdent-for-vscode/error-handling/recovery)

> تفسير الأخطاء والتعافي منها



***

فهم كيفية تفسير الأخطاء والاستجابة لها والإبلاغ عنها يساعدك في الحفاظ على جلسات تطوير منتجة مع Verdent for VS Code.

### ما ستتعلمه [#ما-ستتعلمه]

* أنواع الأخطاء الشائعة وأسبابها
* كيفية تفسير رسائل الخطأ بفعالية
* خطوات منهجية لاستكشاف الأخطاء وإصلاحها
* متى تنتظر ومتى تتخذ إجراءً
* كيفية الإبلاغ عن المشكلات لفريق Verdent

***

## أنواع الأخطاء الشائعة [#أنواع-الأخطاء-الشائعة]

<Warning>
  يجري حاليًا تطوير توثيق شامل للأخطاء. تغطي المعلومات أدناه أكثر فئات الأخطاء شيوعًا. لسيناريوهات أخطاء محددة، تواصل مع [support@verdent.ai](mailto:support@verdent.ai) أو زر مجتمع Discord.
</Warning>

<Tabs>
  <Tab title="من جهة الخادم">
    **أخطاء اكتظاظ الخادم**

    * تحدث خلال فترات الحمل المروري المرتفع
    * قيود مؤقتة في السعة
    * **الإجراء**: انتظر من 5 إلى 10 دقائق ثم أعد المحاولة

    **أخطاء الخادم الداخلية**

    * مشكلات في المعالجة الخلفية
    * انقطاعات مؤقتة في الخدمة
    * **الإجراء**: انتظر وأعد المحاولة، عادةً ما تُحل تلقائيًا

    **خطأ 503 - الخدمة غير متاحة**

    * لا توجد خوادم أعلى سليمة
    * مشكلات مؤقتة في البنية التحتية
    * **الإجراء**: انتظر حتى تتعافى الخدمة

    **أخطاء تحديد المعدل (Rate Limiting)**

    * تجاوز حصص الطلبات
    * إجراءات حماية API من التحميل الزائد
    * **الإجراء**: انتظر حتى إعادة ضبط حد المعدل، وقلّل من تكرار الطلبات
  </Tab>

  <Tab title="المصادقة">
    * بيانات اعتماد غير صالحة أو منتهية الصلاحية
    * مشكلات انتهاء مهلة الجلسة
    * **الإجراء**: أعد المصادقة عبر مركز المستخدم، وتحقق من أن الاشتراك نشط
  </Tab>

  <Tab title="اتصال API">
    * مشكلات في الاتصال بالشبكة
    * جدار حماية أو VPN يحجب الاتصالات
    * قيود شبكة الشركة
    * **الإجراء**: تحقق من اتصال الشبكة، جرّب شبكة مختلفة
  </Tab>

  <Tab title="الإعدادات">
    * إعدادات أو تفضيلات غير صالحة
    * ملفات إعدادات تالفة
    * **الإجراء**: راجع تغييرات الإعدادات الأخيرة، وتحقق من الإعدادات
  </Tab>

  <Tab title="الأذونات">
    * أذونات نظام ملفات غير كافية
    * قيود على الوصول إلى مساحة العمل
    * **الإجراء**: تحقق من أذونات الملفات/المجلدات، وتحقق من الوصول إلى مساحة العمل
  </Tab>
</Tabs>

***

## تفسير رسائل الخطأ [#تفسير-رسائل-الخطأ]

<Warning>
  دليل تفصيلي لتفسير رسائل الخطأ قيد الإعداد. بالنسبة لرسائل الخطأ المحددة التي تواجهها، استخدم زر الملاحظات (Feedback) أو مجتمع Discord للحصول على المساعدة.
</Warning>

<Tabs>
  <Tab title="أخطاء من جهة الخادم">
    الأخطاء من جهة الخادم مؤقتة وعادةً ما تُحل بالانتظار. لا حاجة لأي إجراء سوى إعادة المحاولة بعد بضع دقائق.

    **ابحث عن هذه الكلمات المفتاحية:**

    * "Overloaded" أو "at capacity"
    * "Internal server error" أو "backend processing"
    * "503 Service Unavailable" أو "no healthy upstream"
    * "Rate limit" أو "quota"

    **ما يجب فعله:**

    * انتظر من 5 إلى 10 دقائق قبل إعادة المحاولة
    * واصل العمل التطويري المحلي
    * راجع التغييرات البرمجية التي أُجريت حتى الآن
    * قم بتثبيت (commit) العمل الحالي إلى Git

    **قاعدة عامة:** إذا كانت رسالة الخطأ تشير إلى حالة الخادم أو السعة أو حدود المعدل، فهذا مؤقت. هذه مشكلات في البنية التحتية تُحل تلقائيًا.

    <Note>
      الأخطاء المؤقتة في الخادم (502، 503، 504) عادةً ما تُحل خلال دقائق. انتظر من دقيقتين إلى 3 دقائق قبل إعادة المحاولة.
    </Note>

    **متى تتصعّد:**

    * يستمر الخطأ لأكثر من 15 دقيقة
    * تحقق من Discord لمعرفة تقارير عن انقطاع الخدمة
    * ابحث عن تحديثات صفحة الحالة
  </Tab>

  <Tab title="أخطاء من جهة العميل">
    الأخطاء من جهة العميل تتطلب إجراءً منك. لن تُحل بالانتظار.

    **ابحث عن هذه المؤشرات:**

    * رسائل متعلقة بالمصادقة أو بيانات الاعتماد
    * أخطاء في الإعدادات
    * أخطاء أذونات الملفات
    * فشل في اتصال الشبكة

    **ما يجب فعله:**

    * **أخطاء المصادقة**: أعد المصادقة عبر مركز المستخدم، وتحقق من أن الاشتراك نشط
    * **أخطاء الإعدادات**: راجع تغييرات الإعدادات الأخيرة، وتحقق من ملفات الإعدادات
    * **أخطاء الأذونات**: تحقق من أذونات الملفات/المجلدات، وتحقق من الوصول إلى مساحة العمل
    * **أخطاء الشبكة**: اختبر اتصال الإنترنت، جرّب شبكة مختلفة، تحقق من VPN/جدار الحماية

    **قاعدة عامة:** إذا كانت رسالة الخطأ تشير إلى المصادقة أو الإعدادات أو الأذونات أو الإعدادات المحلية، فأنت بحاجة إلى اتخاذ إجراء تصحيحي.

    **خطوات استكشاف الأخطاء وإصلاحها:**

    1. اقرأ رسالة الخطأ الكاملة للحصول على إرشادات محددة
    2. حدد المكوّن الذي أبلغ عن الخطأ (المصادقة، الإعدادات، الأذونات، الشبكة)
    3. اتخذ إجراءً مستهدفًا بناءً على نوع الخطأ
    4. تحقق من الإصلاح بإعادة تنفيذ العملية الأصلية
  </Tab>
</Tabs>

### قراءة سياق الخطأ [#قراءة-سياق-الخطأ]

عند حدوث الأخطاء:

1. **اقرأ رسالة الخطأ الكاملة** - لا تتجاوز التفاصيل
2. **لاحظ رموز الخطأ** - الرموز المحددة تساعد في تشخيص المشكلات
3. **حدد المكوّن** - ما هو النظام الذي أبلغ عن الخطأ (الخادم، API، المحلي)
4. **تحقق من التوقيت** - هل حدث فورًا أم بعد تأخير؟

***

## استكشاف الأخطاء وإصلاحها بشكل منهجي [#استكشاف-الأخطاء-وإصلاحها-بشكل-منهجي]

اتبع هذه الخطوات التدريجية عندما يتصرف Verdent بشكل غير متوقع، بدءًا بالإجراءات الأقل تأثيرًا.

### الاستجابة الأولية [#الاستجابة-الأولية]

<Steps>
  <Step title="انتظر ولاحظ">
    تحقق مما إذا كان السلوك ثابتًا أو متقطعًا. لاحظ الإجراء الذي أدى إلى السلوك غير المتوقع. لا تفترض فورًا أن هناك خللًا - العديد من المشكلات مؤقتة.
  </Step>

  <Step title="إعادة تشغيل أساسية">
    أعد تشغيل Verdent for VS Code (أغلق VS Code وأعد فتحه). غالبًا ما يحل هذا الحالات العالقة أو مشكلات الأداء. هذه هي أبسط خطوة أولى لاستكشاف الأخطاء وإصلاحها.
  </Step>
</Steps>

### استكشاف الأخطاء وإصلاحها التدريجي [#استكشاف-الأخطاء-وإصلاحها-التدريجي]

إذا لم تحل إعادة التشغيل الأساسية المشكلة:

<Tip>
  اتبع خطوات استكشاف الأخطاء وإصلاحها المنهجية بالترتيب، فتخطي الخطوات غالبًا ما يعني تفويت السبب الجذري.
</Tip>

<Steps>
  <Step title="تحقق من اتصال الشبكة">
    اختبر اتصال الإنترنت بمواقع أخرى. جرّب على شبكة مختلفة (نقطة اتصال الهاتف المحمول) لاستبعاد مشكلات جدار الحماية/VPN. تحقق مما إذا كانت شبكة الشركة تحجب الاتصالات.
  </Step>

  <Step title="تحقق من الإعدادات">
    تحقق من أنك لا تزال مصادقًا. تحقق من أن الاشتراك نشط في مركز المستخدم. راجع تغييرات الإعدادات الأخيرة التي قد تؤثر على السلوك.
  </Step>

  <Step title="اطلب المساعدة">
    تحقق من مجتمع Discord لمعرفة تقارير مماثلة: [https://discord.com/invite/NGjXEZcbJq](https://discord.com/invite/NGjXEZcbJq). استخدم زر الملاحظات (Feedback) للإبلاغ عن المشكلة. أدرج وصفًا للسلوك غير المتوقع وخطوات إعادة إنتاجه.
  </Step>
</Steps>

### ما يجب عدم فعله [#ما-يجب-عدم-فعله]

تجنب هذه الإجراءات بالنسبة للمشكلات المؤقتة:

* لا تعد تثبيت Verdent فورًا
* لا تمسح ذاكرة التخزين المؤقت أو بيانات التطبيق الخاصة بـ VS Code
* لا تعدّل إعدادات النظام بسبب مشكلات مؤقتة
* لا تعد تشغيل الكمبيوتر إلا إذا كانت تطبيقات أخرى متأثرة أيضًا

<Warning>
  في Manual Accept Mode، لا توافق أبدًا على عمليات مدمرة (rm، DROP، DELETE) دون مراجعة الأمر الدقيق بعناية.
</Warning>

**لماذا؟** هذه الإجراءات تستغرق وقتًا طويلاً ونادرًا ما تحل المشكلات. معظم المشكلات تُحل بإعادة تشغيل بسيطة أو بانتظار زوال مشكلات الخادم المؤقتة.

***

## متى تنتظر ومتى تتصرف [#متى-تنتظر-ومتى-تتصرف]

فهم ما إذا كان يجب الانتظار أو اتخاذ إجراء يمنع إهدار جهد استكشاف الأخطاء وإصلاحها.

<Tabs>
  <Tab title="انتظر (5-10 دقائق)">
    تُحل هذه الأخطاء تلقائيًا - لا حاجة لأي إجراء سوى الانتظار وإعادة المحاولة.

    **أخطاء اكتظاظ الخادم أو السعة:**

    * رسائل "Overloaded" أو "at capacity"
    * فترات الحمل المروري المرتفع
    * انقطاعات مؤقتة في الخدمة

    **تحديد المعدل (Rate limiting):**

    * رسائل "Rate limit" أو "quota exceeded"
    * عدد كبير جدًا من الطلبات في وقت قصير
    * حماية API من التحميل الزائد

    **مشكلات اتصال متقطعة:**

    * طلبات فاشلة أحيانًا تنجح عند إعادة المحاولة
    * اهتزازات في الشبكة
    * انقطاعات اتصال قصيرة

    **ما يجب فعله أثناء الانتظار:**

    * واصل العمل التطويري المحلي
    * راجع التغييرات البرمجية التي أُجريت حتى الآن
    * خطط للخطوات التالية أو المهام
    * قم بتثبيت (commit) العمل الحالي إلى Git

    **مدة الانتظار:**

    * الانتظار المعتاد: 5 إلى 10 دقائق
    * إذا استمر الفشل بعد 10 دقائق، انتقل إلى استكشاف الأخطاء وإصلاحها
    * تحقق من Discord لمعرفة تقارير عن مشكلات واسعة الانتشار
  </Tab>

  <Tab title="اتخذ إجراءً فوريًا">
    لن تُحل هذه الأخطاء بالانتظار - يجب عليك اتخاذ إجراء تصحيحي.

    **فشل المصادقة:**

    * انتهت صلاحية الجلسة ← أعد المصادقة عبر مركز المستخدم
    * بيانات اعتماد غير صالحة ← تحقق من أن الاشتراك نشط
    * الحاجة لإعادة المصادقة ← تحقق من مركز المستخدم

    **أخطاء مستمرة (10 دقائق أو أكثر):**

    * نفس الخطأ يتكرر بعد عدة محاولات ← ابدأ استكشاف الأخطاء وإصلاحها
    * نمط فشل ثابت ← تحقق من الإعدادات
    * يستمر الخطأ عبر عمليات إعادة التشغيل ← تحقق من البيئة

    **مشكلات الإعدادات:**

    * تم تغيير الإعدادات مؤخرًا ← راجع التغييرات وتراجع عنها
    * إعداد أو تثبيت جديد ← تحقق من ملفات الإعدادات
    * تغيرت بيئة الشبكة ← اختبر الاتصال

    **أخطاء الأذونات:**

    * رُفض الوصول إلى نظام الملفات ← تحقق من أذونات الملفات/المجلدات
    * قيود مساحة العمل ← تحقق من الوصول إلى مساحة العمل
    * أذونات المجلدات ← امنح الأذونات اللازمة

    **مشكلات الشبكة:**

    * عدم القدرة الكاملة على الاتصال ← اختبر اتصال الإنترنت
    * حجب من VPN أو جدار الحماية ← جرّب شبكة مختلفة
    * قيود شبكة الشركة ← تواصل مع دعم تقنية المعلومات

    **قاعدة القرار:**

    * أخطاء الخادم/حدود المعدل ← انتظر
    * المصادقة/الإعدادات/الأذونات/الشبكة ← تصرّف فورًا
    * غير متأكد؟ ← انتظر من 5 إلى 10 دقائق أولًا، ثم تصرّف إذا استمرت المشكلة
  </Tab>
</Tabs>

***

## تقديم سياق الخطأ [#تقديم-سياق-الخطأ]

عند طلب المساعدة أو الإبلاغ عن المشكلات، أدرج سياقًا شاملاً لتشخيص أسرع.

### المعلومات الأساسية [#المعلومات-الأساسية]

**تفاصيل الخطأ:**

* نص رسالة الخطأ الدقيق (انسخه والصقه، لا تُعِد صياغته)
* رمز الخطأ إن وُجد
* الطابع الزمني لحدوث الخطأ
* التكرار (مرة واحدة، متقطع، ثابت)

**البيئة:**

* إصدار Verdent for VS Code
* إصدار VS Code
* نظام التشغيل وإصداره
* بيئة الشبكة (منزلية، شركة، VPN)

**خطوات إعادة الإنتاج:**

1. ما الذي كنت تحاول فعله
2. الـ prompts أو الأوامر الدقيقة المستخدمة
3. الملفات أو السياق المعني
4. الإجراءات المتخذة قبل حدوث الخطأ

**السياق:**

* وضع التنفيذ الذي كنت تستخدمه
* حجم وتعقيد مساحة العمل
* تغييرات الإعدادات الأخيرة
* عمليات ناجحة مماثلة سابقة

### مثال على تقرير خطأ [#مثال-على-تقرير-خطأ]

تنسيق جيد لتقرير الخطأ:

```
Issue: Getting "Internal server error" when requesting code analysis

Error Message (exact):
"Error: Internal server error occurred during processing. Please try again later."

Environment:
- Verdent for VS Code v1.2.3
- VS Code 1.85.0
- macOS 14.2
- Home network (no VPN)

Steps to Reproduce:
1. Opened large TypeScript project (500+ files)
2. Used Auto-Run Mode
3. Requested: "Analyze authentication flow in auth.ts and suggest improvements"
4. Error occurred immediately after request

Additional Context:
- First time working with this project
- Same request worked fine yesterday in different project
- Other requests (small file edits) work normally
```

### ما الذي يجعل هذا فعالًا [#ما-الذي-يجعل-هذا-فعالًا]

* نص رسالة الخطأ الدقيق
* تفاصيل بيئة كاملة
* خطوات إعادة إنتاج واضحة
* مقارنة مع سيناريوهات عمل ناجحة
* سياق إضافي حول الأنماط

***

## الإبلاغ عن المشكلات [#الإبلاغ-عن-المشكلات]

<Tabs>
  <Tab title="زر الملاحظات (Feedback)">
    **الموقع:** الشريط العلوي للوحة Verdent

    **ما الذي يفعله:**

    * يفتح نافذة منبثقة لإرسال المشكلات والاقتراحات
    * قناة مباشرة لفريق Verdent
    * الأنسب لتقارير الأخطاء وطلبات الميزات

    **متى تستخدمه:**

    * أخطاء مؤكدة مع خطوات واضحة لإعادة الإنتاج
    * طلبات ميزات مع حالات استخدام محددة
    * الحاجة إلى تواصل مباشر مع الفريق
    * مشكلات غير عاجلة تتطلب التحقيق

    **ما يجب تضمينه:**

    * وصف واضح للمشكلة
    * رسائل الخطأ (النص الدقيق)
    * خطوات إعادة الإنتاج
    * السلوك المتوقع مقابل الفعلي
    * إصدار Verdent والمنصة
    * متى بدأت المشكلة
  </Tab>

  <Tab title="مجتمع Discord">
    **الرابط:** [https://discord.com/invite/NGjXEZcbJq](https://discord.com/invite/NGjXEZcbJq)

    **ما الذي يوفره:**

    * مجتمع نشط من مستخدمي Verdent وأعضاء الفريق
    * مساعدة فورية في استكشاف الأخطاء وإصلاحها
    * مشاركة المشكلات مع لقطات الشاشة
    * الحصول على المساعدة من مستخدمين ذوي خبرة
    * نقاشات مجتمعية وحلول بديلة

    **متى تستخدمه:**

    * مشكلات عاجلة تتطلب نقاشًا فوريًا
    * استكشاف أخطاء معقدة يتطلب تبادل الآراء
    * إسهام المجتمع حول أفضل الممارسات
    * أسئلة سريعة قبل تقديم تقارير رسمية
    * مشاركة الحلول البديلة مع المجتمع
  </Tab>

  <Tab title="اختيار القناة">
    | نوع المشكلة                          | استخدم زر الملاحظات | استخدم Discord |
    | ------------------------------------ | :-----------------: | :------------: |
    | خطأ مؤكد مع خطوات إعادة الإنتاج      |          ✓          |                |
    | طلب ميزة                             |          ✓          |                |
    | حاجة عاجلة لاستكشاف الأخطاء وإصلاحها |                     |        ✓       |
    | مشكلة معقدة تتطلب نقاشًا             |                     |        ✓       |
    | سؤال سريع                            |                     |        ✓       |
    | رغبة في إسهام المجتمع                |                     |        ✓       |
    | تقرير خطأ رسمي                       |          ✓          |                |
    | مساعدة عامة                          |                     |        ✓       |

    **ما لا يجب الإبلاغ عنه:**

    * أخطاء خادم مؤقتة (أقل من 10 دقائق)
    * فترات الحمل المروري المرتفع
    * مشكلات موثقة مسبقًا
    * السلوك المتوقع

    **بدلاً من ذلك:** انتظر انتهاء المشكلات المؤقتة، وتحقق من Discord للاطلاع على التقارير الحديثة، وراجع التوثيق.
  </Tab>
</Tabs>

***

## أفضل ممارسات الوقاية [#أفضل-ممارسات-الوقاية]

الممارسات الاستباقية تقلل من تكرار الأخطاء وتحسّن التعافي عند حدوثها.

<Tip>
  استخدم لغة محددة في الـ prompts وأدرج سياق الملفات ذي الصلة لمنع العديد من الأخطاء الشائعة قبل حدوثها.
</Tip>

### قبل بدء العمل [#قبل-بدء-العمل]

**1. تحقق من الإعداد**

* تحقق من حالة المصادقة في مركز المستخدم
* تأكد من أن الاشتراك نشط
* تأكد من استقرار اتصال الشبكة
* راجع تغييرات الإعدادات الأخيرة

**2. تهيئة Git**

* احرص دائمًا على وجود التحكم بالإصدارات قبل استخدام الأوضاع المرنة
* ثبّت (commit) العمل الحالي للحصول على نقطة بداية نظيفة
* يوفر خيار التراجع في حال حدوث مشكلات

**3. تحقق من رصيد الأرصدة**

* تحقق من كفاية الأرصدة للعمل المخطط له
* اشحن الأرصدة إذا لزم الأمر قبل بدء مهام معقدة
* تجنب الانقطاعات في منتصف المهمة بسبب نفاد الأرصدة

### أثناء التطوير [#أثناء-التطوير]

**1. استخدم أوضاع تنفيذ مناسبة**

* القبول اليدوي للكود غير المألوف
* Plan Mode للتغييرات المعقدة
* التشغيل التلقائي فقط مع وجود شبكة أمان Git
* طابق الوضع مع مستوى الخطورة

**2. راقب الأداء**

* انتبه لتراجع جودة الاستجابة
* لاحظ أوقات الاستجابة الأبطأ
* ابدأ جلسات جديدة عند تراجع الأداء
* تتبع استخدام السياق يدويًا

**3. prompts واضحة ومحددة**

* تقلل الأخطاء الناتجة عن سوء فهم الطلبات
* أدرج السياق والقيود ذات الصلة
* أشر إلى الأنماط الموجودة
* حدد النطاق بوضوح

### بعد الأخطاء [#بعد-الأخطاء]

**1. تعلّم من الأنماط**

* لاحظ ما الذي تسبب في الأخطاء
* حدد الظروف القابلة لإعادة الإنتاج
* عدّل سير العمل لتجنب المسببات
* شارك النتائج مع المجتمع

**2. وثّق الحلول البديلة**

* احتفظ بملاحظات حول الحلول الفعالة
* شاركها مع أعضاء الفريق
* ساهم في معرفة المجتمع
* أبلغ فريق Verdent للحصول على إصلاحات

**3. حدّث الإعدادات**

* عدّل الإعدادات بناءً على الخبرة
* حسّن سير عملك
* اضبط القواعد لمنع المشكلات
* حافظ على توثيق AGENTS.md

***

## طالع أيضًا [#طالع-أيضًا]

<CardGroup cols="3">
  <Card title="هندسة الـ Prompt" href="/docs/verdent-for-vscode/best-practices/prompts" icon="message">
    اكتب prompts فعالة لتقليل الأخطاء
  </Card>

  <Card title="إدارة السياق" href="/docs/verdent-for-vscode/best-practices/context" icon="layer-group">
    حسّن السياق لمنع مشكلات الأداء
  </Card>

  <Card title="أوضاع التنفيذ" href="/docs/verdent-for-vscode/execution-modes/overview" icon="toggle-on">
    اختر الأوضاع المناسبة لتقليل المخاطر
  </Card>
</CardGroup>