إن واصلت البرمجة بالذكاء الاصطناعي، فلا بدّ أن تلقى الأخطاء. لحظة ظهور الحروف الحمراء تتوقّف يدك ― وذلك الوقت هو ألدّ أعداء الإنتاجية. لكن اطمئنّ: الأخطاء التي تصادفها في أدوات البرمجة بالذكاء الاصطناعي، وعلى رأسها Claude Code، معظمها تكرار لأنماط محدّدة. فما إن تميّز النوع حتى تتحدّد المعالجة شبه آلياً. هذا الفصل خريطة فرز الأعطال (triage) تفتحها أول ما تتعثّر.
أن تصبح شخصاً «لا تُوقفه الأخطاء»
🧭 أولاً مقال جامع واحد. الملخّص الشامل الذي يجمع الأخطاء الشائعة عرضياً هو «ملخّص أخطاء Claude Code الشائعة وطرق معالجتها». هذا الفصل خريطة تطلّ على كل فئة، والمقالات الفردية المرتبطة تحمل أمثلة الرسائل الملموسة والخطوات. احفظه في المفضّلة، وحين تتعثّر ابدأ من هنا.
افرز الأخطاء بحسب «النوع»
أول خطوة في المعالجة أن تميّز «من أيّ نوع هذا الخطأ». فإذا اختلفت طبقة السبب، اختلف موضع الإصلاح. قبل أن تتعمّق في قراءة الرسائل الدقيقة، ضعه أولاً في إحدى الفئات الست التالية. بمجرّد أن تضعه فيها، تكون قد حسمت 80% من المعالجة.
لا يشتغل أصلاً / لا يوجد الأمر. مشكلة المدخل. ↓ بالتفصيل
لا يمكن الدخول / تنقطع المصادقة. الاتصال بالحساب. ↓ بالتفصيل
لا يتّصل / ازدحام الخادم. مشكلة المسار وجانب الخادم. ↓ بالتفصيل
بلغت الحدّ / وقت لا يمكن الاستخدام فيه. مشكلة الخطة والاستهلاك. ↓ بالتفصيل
طويل جداً / محشوّ أكثر من اللازم. مشكلة كمّ المعلومات المُسلَّم. ↓ بالتفصيل
يفشل استدعاء الإضافة/الأداة. مشكلة الميزات المحيطة. ↓ بالتفصيل
💡 حيلة التمييز. كلمة مفتاحية واحدة في نصّ الخطأ تعطيك الحدس. command not found ← ①، authentication/login ← ②، connection/network/529 ← ③، usage limit ← ④، too long ← ⑤، MCP/tool ← ⑥. قبل أن تقرأ الرسالة بأكملها، ابحث أولاً عن هذه الكلمة.
① التثبيت والتشغيل ― الأمر غير موجود
أول عقبة هي «لا يشتغل أصلاً». فقد يكون التثبيت فشل في منتصفه، أو المسار (PATH) غير معدّ، فلا يستجيب حين تكتب الأمر. وبما أنك لا تتقدّم إن تعثّرت هنا، فتأنّ وتحقّق من المدخل.
العرَض: حين تكتب claude يردّ «لا يوجد أمر كهذا».
السبب: المسار غير معدّ إلى موضع التثبيت، أو الصدفة لم يُعَد تحميلها، أو التثبيت نفسه لم يكتمل.
المعالجة: أعِد فتح الطرفية / تحقّق من PATH / أعِد التثبيت. إن جرّبتها بالترتيب خرجت غالباً.
العرَض: يتوقّف أثناء التثبيت بخطأ / يُرفض بسبب الأذونات (permission).
السبب: نسخة Node.js قديمة، أو نقص الأذونات، أو فشل جلب الحزمة عبر الشبكة.
المعالجة: حدّث البيئة الأساسية (Node وغيره)، وراجع صلاحيات المدير وطريقة التثبيت. وفي شبكة الشركة اشتبه بالوسيط (proxy) أيضاً.
🔧 الخطوات التفصيلية هنا. تمييز أسباب فشل التثبيت وcommand not found وطرق الإصلاح الملموسة جمعناها في «كيف تصلح command not found / خطأ التثبيت». وإن تعثّرت في التثبيت، فأقصر طريق أن تعيد تثبيته وفق خطوات الفصل الثاني «ابدأ مع Claude Code».
② تسجيل الدخول والمصادقة ― المصادقة لا تمرّ
نمط يشتغل فيه البرنامج، لكن يُرفض عند تسجيل الدخول أو المصادقة. يظهر بصور مثل عدم نجاح مصادقة المتصفح، أو أنك بعد استخدام لفترة خرجت من الحساب فجأةً. حالة يكون فيها «تصافح» الحساب والأداة قد اختلّ.
العرَض: لا تتقدّم من شاشة الدخول / يُرفض بخطأ مصادقة / لا يُفتح متصفح المصادقة.
السبب: انتهاء صلاحية رمز المصادقة أو تلفه، فشل إعادة التوجيه، الخلط بين الخطة أو الحساب المقصود، اختلاف الوقت.
المعالجة: اخرج من الحساب وادخل من جديد / امسح بيانات المصادقة المحفوظة وأعِد المصادقة / تحقّق أنه الحساب الصحيح.
قد يبدو الأمر «خطأ مصادقة» بينما هو في الحقيقة مجرّد اختلاف الخطة أو العقد المقصود.
من يستخدم عدة حسابات، فليتحقّق أولاً من الحساب المسجّل الدخول ونوع الخطة. الخلط بين حساب الشركة والحساب الشخصي مزلق نموذجي.
🔑 الخطوات التفصيلية هنا. خطوات إعادة الدخول وإعادة جلب الرمز حين لا تمرّ المصادقة تجدها في «معالجة خطأ تسجيل الدخول والمصادقة». معظمها يُحلّ بإعادة الدخول، وإن لم يُحلّ فاشتبه بجانب الشبكة (③) أيضاً.
③ الاتصال والشبكة ― لا يتّصل أو ازدحام
هنا ينقسم السبب إلى «جانبك» و«جانب الخادم»، فالتمييز جوهري. هل خطّك أو وسيطك (proxy) يسدّ الطريق، أم أن الخادم مزدحم مؤقّتاً؟ الأول تصلحه بنفسك، والثاني منهجه الأساسي الانتظار أو التخفيف.
العرَض: لا يتّصل / انتهاء المهلة / ينقطع الاتصال في منتصفه.
السبب: خلل في خطّ الإنترنت، حجب من وسيط الشركة أو الجدار الناري، VPN، مشكلة شهادة أو DNS.
المعالجة: جرّب خطاً آخر / أوقف VPN / راجع إعداد الوسيط. وفي شبكة الشركة تحقّق من المدير عمّا هو مسموح.
العرَض: يعود overloaded أو 5xx. يفشل مع أن إعدادك صحيح.
السبب: حمل أو عطل مؤقّت في جانب الخادم. ليس بسبب شيفرتك أو إعدادك.
المعالجة: انتظر قليلاً وأعِد المحاولة / تجنّب أوقات الازدحام / تحقّق من معلومات العطل (صفحة الحالة).
⚠️ مقياس التمييز. إن كانت المواقع والخدمات الأخرى سليمة وأداة الذكاء الاصطناعي وحدها تسقط، فالأرجح جانب الخادم (529/500)، والمعالجة «الانتظار». وإن كان سائر اتّصالاتك غير مستقرّ، فهو جانبك (الخطّ، الوسيط، VPN). للتفاصيل راجع «خطأ الاتصال والشبكة والوسيط» و«معنى ومعالجة خطأ 529 overloaded / 500».
④ حدود الاستخدام ― بلغت الحدّ
ليس خطأً بل إشعار «بلغت الحدّ فلا يمكنك الاستخدام الآن». لكل خطة حدّ أعلى للاستهلاك في مدة زمنية معيّنة أو في الأسبوع، فإن لمسته توقّفت مؤقّتاً. وبما أنه ليس عطلاً، فالصواب أن تعدّل الاستخدام والخطة بدلاً من محاولة الإصلاح.
العرَض: يظهر «بلغت حدّ الاستخدام»، فلا يمكنك الاستخدام حتى وقت معيّن.
السبب: بلوغ حدّ استهلاك الخطة. تلمسه أسرع إن أدرت مهام كبيرة أو محادثات طويلة في وقت قصير.
المعالجة: انتظر إعادة الضبط / قسّم المحادثة واستخدم بخفّة / راجع الخطة إن لزم.
العرَض: تبلغ الحدّ في منتصف الأسبوع / يبدو توقيت إعادة الضبط أبكر أو أبطأ مما ظننت.
السبب: قد يُحتسب الحدّ الأسبوعي ابتداءً من أول استخدام لا بالضرورة وفق الأسبوع التقويمي.
المعالجة: افهم طريقة احتساب إعادة الضبط بشكل صحيح، ووزّع الأعمال كثيرة الاستهلاك بتخطيط.
📊 الحدود تُتجنّب غالباً بـ«الإدارة». معنى الحدّ وطريقة تقدير وقت الانتظار في «معالجة بلوغ حدّ الاستخدام»، وطريقة احتساب إعادة الضبط الأسبوعية في «آلية إعادة ضبط الحدّ الأسبوعي مبكّراً». أما الاستخدام الأقلّ ملامسةً للحدّ فنتناوله مجتمعاً في الفصل السابع «التكلفة والكفاءة».
⑤ الإدخال والسياق ― طويل جداً
لكمّ المعلومات الذي يتعامل معه الذكاء الاصطناعي دفعةً واحدة (السياق) حدّ أعلى. فإن طالت المحادثة، أو سلّمته ملفاً ضخماً بأكمله، رُفض بـ«الإدخال طويل جداً». هذه إشارة إلى الحشو الزائد، والمعالجة أن تقلّل الكمّ المُسلَّم وتقسّمه.
العرَض: يظهر «الإدخال طويل جداً» فلا تُنفَّذ التعليمة.
السبب: تراكم سجلّ المحادثة، تحميل ملف ضخم أو ملفات كثيرة، سجلّ ملصوق طويل جداً.
المعالجة: نظّم المحادثة ولخّصها / ابدأ محادثة جديدة / سلّم النطاق اللازم فقط / قسّم المهمة صغيراً.
العرَض: يظهر خطأ في معالجة التفكير (thinking) فيُقطع الردّ.
السبب: عدم اتّساق حالة المحادثة، أو تعارض داخلي مرتبط بالسجلّ. يحدث بسهولة في المحادثات الطويلة.
المعالجة: ابدأ محادثة جديدة / افصل التبادل المعني. معظمه يُحلّ بالتحديث.
✂️ «الطول» يُمنع بالتصميم. طرق التقليل الملموسة في «معالجة prompt is too long»، وأعطال محيط thinking في «معالجة خطأ thinking block». أما العلاج الجذري فهو تقسيم المهمة صغيراً، وهو متّصل مباشرةً بأسلوب التعليمات في الفصل الرابع «اطلب بإتقان».
⑥ MCP والأدوات ― الإضافة لا تعمل جيداً
ربط MCP (ربط الأدوات الخارجية) واستدعاء الأدوات قد يفشل فيه المحيط من الإضافات وحده مع أن Claude Code نفسه سليم. الحيلة أن تميّزه عن أخطاء البرنامج نفسه. تحقّق أولاً «هل يتكرّر إن أزلت الإضافة»، فيتقدّم تمييز السبب دفعةً واحدة.
العرَض: لا يتّصل بخادم MCP / لا تظهر الأدوات المرتبطة في القائمة أو لا تستجيب.
السبب: خطأ في كتابة ملف الإعداد، فشل تشغيل الخادم، نقص المسار أو التبعيات، نقص بيانات المصادقة.
المعالجة: راجع الإعداد / تحقّق من تشغيل الخادم منفرداً / أزله مرةً وميّز هل يعمل البرنامج وحده.
العرَض: يفشل استدعاء الأداة / يتوقّف عند تمرير نتيجة الاستدعاء.
السبب: عدم اتّساق تعريف الأداة أو الوسائط، اختلال حالة المحادثة، خلل مؤقّت في الجهة المرتبطة.
المعالجة: أعِد ترتيب المحادثة / عطّل الأداة المعنية مؤقّتاً لتمييز السبب / تحقّق من حالة الجهة المرتبطة.
العرَض: يقع خطأ في فحص الحالة المتعلّق بـ PR (طلب السحب).
السبب: غالباً يتعلّق بإعداد أو أذونات CI أو الفحص المرتبط، أو بحالة الخدمة الخارجية.
المعالجة: تحقّق من إعداد الفحص وأذوناته / أعِد التشغيل / تحقّق من حالة الخدمة الخارجية.
🧩 الإضافات «تُزال للتمييز». إصلاح اتصال MCP في «معالجة خطأ اتصال خادم MCP»، وأعطال استدعاء الأدوات في «معالجة خطأ استدعاء الأداة»، وما يتعلّق بفحص PR في «معالجة خطأ فحص حالة PR». أما استخدام الإضافات نفسها فنتناوله في الفصل السادس «استخدم الإضافات».
كيف تخرج حين تتعثّر ― خمس حيل شاملة
حتى حين يتعذّر تحديد السبب فوراً، هناك «حيلة شاملة تجرّبها أولاً». فكثير من الأخطاء يختفي بمجرّد تحديث الحالة أو تخفيف الحمل. حين لا تصيب الحدس في الفئات أعلاه، جرّب هذه الخمس بالترتيب من الأعلى.
أغلق الأداة والطرفية وأعِد فتحهما. اختلالات الحالة المؤقّتة، يختفي معظمها بهذا وحده. أول حيلة تشتبه بها.
المحادثة الطويلة مرتع عدم الاتّساق. ابدأ محادثة جديدة أو لخّص السجلّ ونظّمه (بفكرة /compact) لتخفّ. ينفع لـ⑤.
لا تطلب كبيراً دفعةً واحدة، بل قسّم المهمة إلى خطوات صغيرة. الأخطاء الناجمة عن الطول أو الثقل تُتجنّب بهذا من الجذر.
529/500 والازدحام يحلّها الوقت. انتظر دقائق وأعِد. وتحقّق من معلومات العطل في صفحة الحالة. ينفع لـ③④.
إن لم تفهم مطلقاً، سلّم نصّ الخطأ بأكمله للذكاء الاصطناعي أو للبحث. وبمقابلته بالمقال الجامع لهذا الفصل، يصيب غالباً نمطاً معروفاً.
🧯 عدم الارتباك أكبر معالجة. الخطأ ليس إشارة «تعطّل» بل تلميحة «أصلِح هنا». ميّز الفئة، وجرّب الحيل الخمس، وإن لم يُجدِ فإلى المقالات الفردية. ما إن تتقن هذا التدفّق حتى لا تخيفك الحروف الحمراء بعد.
- افرز الخطأ أولاً إلى ست فئات (التثبيت، المصادقة، الاتصال، حدود الاستخدام، السياق، MCP/الأدوات). كلمة مفتاحية واحدة تعطي الحدس.
- لكل فئة عرَض ← سبب ← معالجة شبه قالبية. جانب الخادم مثل 529/500 «الانتظار»، والطويل جداً «التقسيم والتنظيم» أساساً.
- حتى مع مجهول السبب، تخرج من معظمها بـالحيل الخمس الشاملة (إعادة التشغيل، إعادة ترتيب المحادثة، التقسيم صغيراً، الانتظار والإعادة، تسليم نصّ الخطأ كما هو).
- الخطوات الملموسة في المقال الجامع والمقالات الفردية. إدارة الحدود في الفصل السابع، والإضافات في الفصل السادس.
حين تُتقن التعامل مع الأخطاء، تمضي البرمجة بالذكاء الاصطناعي إلى الأمام دفعةً واحدة. والآن دور توسيع قدرة Claude Code نفسها. في الفصل السادس «استخدم الإضافات»، لنقوِّ رفيقنا أكثر بـ hooks وplugins وsubagents وMCP.