إن واصلت استعمال Claude Code فستتعثّر حتماً. وهذا الفصل ليس معجماً للأخطاء، بل فصل تكتسب فيه ترتيب التشخيص الذي ينزل بك من العرَض إلى السبب.
ومتى ملكت هذا الترتيب، استطعت الحكم على «أي فئة هذه» حتى مع نصّ خطأ تراه لأول مرة. أما مقالات المعالجة المفردة فيكفي أن تقرأها بعد ذلك.
ما تفعله قبل أن تبحث عن نصّ الخطأ
عند التعثّر يبحث كثيرون عن نصّ الخطأ كما هو. وهذا نافع أيضاً، لكن التأكّد من ثلاثة أشياء أولاً أسرع في أغلب الأحوال.
إن كان يعمل، فالسبب ليس البيئة بل التغيّر الأخير. محادثة طالت، أو إعداد أضفته، أو شبكة بدّلتها.
إن وقع كل مرة فالسبب إعداد أو بيئة. وإن وقع أحياناً فازدحام أو خطّ اتصال، وكثيراً ما لا يكون السبب عندك أصلاً.
أعند التشغيل، أم لحظة إرسال التعليمة، أم في أثناء الردّ؟ موضع التوقّف يحدّد الفئة تقريباً.
وCHECK 3 أعظمها أثراً. فإن عرفت أين توقّف من دورة الجمع والتنفيذ والتحقّق التي رأيناها في الفصل الأول، ضاقت الاحتمالات دفعة واحدة.
التصنيف إلى خمس فئات
تنقسم أخطاء Claude Code إلى خمس فئات بحسب موضع السبب. فحدّد أولاً أيّها.
هل يبدأ أصلاً؟
لا ← مشكلة في التطبيق نفسه (انظر الملحق أدناه)
نعم
↓
هل تستطيع إرسال تعليمة؟
لا، يرفضها ← 1. المصادقة
نعم
↓
هل يعود ردّ؟
لا، لا يصل شيء أو ينقطع في الأثناء ← 2. الاتصال
يقول «بلغت الحدّ» ← 3. حدود الاستعمال
يقول «طويل جداً» ← 4. السياق
نعم
↓
يفشل كلما دخلت أداة خارجية ← 5. الأدوات والامتدادات
خمّن موضعك بهذا التفريع ثم انتقل إلى القسم المناسب أدناه. فـلكل فئة قالب معالجة مختلف، وخلطها في التجريب يذيب وقتك.
1. المصادقة ― لا يقبل إثبات هويّتك
العرَض أن يقال لك «لم تسجّل الدخول»، أو أن تُرفض بحجّة أن بيانات الاعتماد غير صالحة. وسِمَته أنه يتوقّف قبل إرسال التعليمة.
انتهاء صلاحية الجلسة / الدخول بحساب آخر / الخلط بين مفتاح API والاشتراك / شبكة الشركة تحجب اتصال المصادقة
سجّل الدخول من جديد، ثم تأكّد بأي حساب دخلت، ثم جرّب خطّاً آخر (مثل مشاركة اتصال الهاتف). فإن صلح بالثالث فهي فئة الاتصال 2
ونسبة ما يُصلَح في هذه الفئة بإعادة تسجيل الدخول عالية، ولذلك يميل الناس إلى التعمّق فيها حين لا تُصلَح. فإن جرّبت مرتين ولم ينفع فاشكك في الفئة 2. فاتصال المصادقة يمرّ بالشبكة أيضاً.
2. الاتصال ― لا يصل شيء أو ينقطع
هذه أكثر الفئات تعرّضاً لسوء الفهم. فليس بالضرورة أن إعدادك هو الخطأ.
والعرَض ينقسم ثلاثة.
حجب من وسيط أو TLS أو شبكة مؤسسية. مشكلة من جهة البيئة، وتُميَّز بتجربة خطّ آخر.
حالة ازدحام من جهة الخدمة. والانتظار هو الصواب، والعبث بالإعداد لا يترك إلا آثاراً جانبية.
نمط يسقط فيه الاتصال في أثناء ردّ طويل. وقد يزول بتقصير المخرجات وتقطيعها.
وقد تناولنا كلاً منها على حدة في معالجة أخطاء الاتصال والوسيط وTLS، وخطأ 529 Overloaded و500، وConnection closed mid-response.
لا تحاول إصلاح الازدحام بالإعدادات. فإن عبثت بعشرة مواضع في الإعداد محاولاً إعادة إنتاج «يفشل أحياناً»، لم تعد تعرف أصلحته أنت أم أصلحه مرور الوقت. فأعد المحاولة بعد مهلة أولاً، وتأكّد هل يقع في كل مرة.
3. حدود الاستعمال ― استنفدت الحصّة
هي الفئة التي يقال لك فيها «بلغت الحدّ». وهي مواصفة لا خطأ، فمحلّ الإصلاح ليس الإعداد بل طريقة الاستعمال.
والذي ينبغي أن تمسكه هنا أن الحصّة ليست نوعاً واحداً. فهناك حصّة بدورة قصيرة وأخرى بدورة أطول، وهما منفصلتان. فإن تعافت إحداهما وبقيت الأخرى، بقي التوقّف قائماً. وهذا في الغالب حقيقة «تعافى قبل قليل ثم توقّف من جديد».
والتفصيل مجموع في معالجة usage limit reached، وفي حقيقة إعادة التعيين المبكّرة للحدّ الأسبوعي الذي تحقّقنا فيه من الحصّة الأسبوعية بالقياس. أما تقليل الاستهلاك نفسه ففي الفصل السابع.
4. السياق ― المدخل أطول من اللازم
هي الفئة التي تُرفض فيها بحجّة «طويل جداً». واعتبرها ظهوراً مباشراً لحديث نافذة السياق في الفصل الأول على هيئة عرَض.
اطوِ السجلّ، أو اقطعه وابدأ من جديد. والأصل أن تطوي عند فاصل العمل.
لا تلصق ملفاً ضخماً أو سجلاً كاملاً. سلّمه الموضع المعني وحده، أو دعه يبحث عنه.
ومعالجة العرَض في أسباب خطأ Prompt is too long ومعالجته، وتقدير موعد الطيّ في هل ينبغي تشغيل /compact يدوياً.
وثمة حالات يُوقَف فيها الإخراج بوصفه مخالفاً للسياسة. وليست مسألة طول، فلا تخلط بينهما. فتلك نمط آخر.
5. الأدوات والامتدادات ― ما وصلته لا يعمل
هي الفئة التي تظهر بعد إضافة خادم MCP أو أداة خارجية. وتمييزها سهل: انظر هل يُصلَح بإزالتها.
أوقف كل الامتدادات
فإن صلح: السبب هو الامتدادات. أعدها واحداً واحداً حتى تحدّد الجاني
وإن لم يصلح: الامتدادات لا علاقة لها. عُد إلى الفئات من 1 إلى 4
ومتى تبيّن أن السبب امتداد، فانتقل إلى أسباب خطأ اتصال MCP ومعالجته. فهو في الغالب إما صيغة الإعداد، وإما مسار أمر التشغيل، وإما الأذونات.
والذي لا تفعله هنا هو أن تشكّك في ذكاء Claude. فإن لم يكن الامتداد موصولاً، تصرّف Claude كأن تلك الأداة غير موجودة. وكثيراً ما يكون سبب «قلت له ولم يفعل» هو الاتصال.
ملحق ― التطبيق نفسه لا يبدأ
إن كنت تستعمل تطبيق سطح المكتب لا نسخة الطرفية، فقد يتوقّف قبل أن يبلغ Claude Code أصلاً. وليس من الفئات الخمس، فأخرجناه من جدول التصنيف.
والنمط الذي يحتاج إلى إصلاح على Windows في خطوات إصلاح «تعذّر فتح هذا التطبيق»، والنمط الذي يتجمّد عند الرسم في أسباب التجمّد مع GPU process gone ومعالجته.
خمس خطوات حين يستمرّ التعثّر
لحين لا تعرف الفئة، أو تعرفها ولا يُصلَح. جرّبها من أعلى إلى أسفل. فهي مرتّبة من الأرخص.
يزول بهذا كل اختلال منشؤه السياق. وهي أرخص الخطوات.
الازدحام والحدود يُحلّان بهذا وحده. ولا تلمس الإعداد.
فإن صلح بهذا، ثبت أن السبب شبكة البيئة عندك.
تمييز الفئة 5. وأعدها واحداً واحداً. فإعادتها جملةً لا معنى لها.
جرّب الشيء نفسه في دليل فارغ. فإن لم يتكرّر، فالسبب من جهة المشروع.
غيّر شيئاً واحداً في المرة. فالتعثّر يدفعك إلى العجلة وتغيير أشياء معاً، وحينها لا تعرف أيّها كان الفاعل، فتبدأ من الصفر مرة أخرى حين يظهر العرَض نفسه لاحقاً. وتحديد خطوة واحدة نافعة أرخص بكثير على المدى الطويل.
وإن أردت البحث انطلاقاً من نصّ خطأ بعينه، فـخلاصة الأخطاء الشائعة وحلولها تصلح فهرساً.
الخلاصة
- قبل البحث عن نصّ الخطأ، انظر في ثلاثة: «هل كان يعمل قبل قليل» و«أيقع كل مرة» و«أين توقّف»
- الأسباب خمس فئات: المصادقة والاتصال وحدود الاستعمال والسياق والأدوات. ولا تخلطها في التجريب
- الازدحام والحدود صوابهما الانتظار. والعبث بالإعداد لا يترك إلا آثاراً جانبية
- الحصّة ليست نوعاً واحداً. هناك دورة قصيرة وأخرى طويلة منفصلتان، فقد يتوقّف من جديد بعد أن يتعافى
- فئة الامتدادات تُميَّز دفعة واحدة بـهل يصلح إن أوقفتها كلها. وأعدها واحداً واحداً
- وإن استمرّ التعثّر فخمس خطوات من الأرخص. وغيّر شيئاً واحداً في المرة
ومتى صرت تخرج من التعثّر، جاء دور تحديد «إلى أي حدّ تفوّض». انتقل إلى الفصل الخامس «الأذونات والأمان».