دليل تصحيح الأخطاء — أخطاء شائعة وحلولها
مرجع للأخطاء التي ستصادفها في هذا المشروع.
أخطاء الواجهة الخلفية
الخطأ ModuleNotFoundError: No module named 'flask'
السبب: التبعيات غير مثبّتة أو البيئة الافتراضية (venv) غير مفعّلة. الحل:
source venv/bin/activate # فعّل البيئة أولًا
pip install -r app/requirements.txt
الخطأ sqlite3.OperationalError: no such table: message
السبب: لم تُنشأ جداول قاعدة البيانات بعد. الحل: داخل صدفة Python:
from app import db
db.create_all()
خطأ استيراد flask_sqlalchemy أو flask_cors
السبب: الحزمة غير مثبّتة. الحل:
pip install flask-sqlalchemy flask-cors python-dotenv openai
الخطأ Port 5000 already in use
السبب: عملية أخرى تستخدم المنفذ 5000. الحل:
# Linux/macOS
kill $(lsof -t -i:5000)
# Windows (PowerShell)
netstat -ano | findstr :5000
taskkill /PID <PID> /F
الخطأ openai.AuthenticationError
السبب: مفتاح API غير صالح أو مفقود في .env.
الحل: تحقق من وجود backend/app/.env وأنه يحتوي على:
OPENAI_API_KEY=sk-...
لا تشارك هذا المفتاح أبدًا، ولا تُدرجه في git.
الخطأ openai.RateLimitError
السبب: تجاوزت الحد المسموح به لمعدل الطلبات أو الحصة المتاحة لك في API. الحل: انتظر دقيقة ثم أعد المحاولة. تحقق من استهلاكك على platform.openai.com.
الخطأ requests.exceptions.ConnectionError
السبب: خادم Flask لا يعمل. الحل: شغّل الخادم في طرفية أخرى:
python app/__init__.py
الخطأ AttributeError: 'NoneType' object has no attribute 'something'
السبب: أعادت دالة القيمة None بينما كنت تتوقع قيمة. غالبًا ما يكون السبب استعلامًا فاشلًا على قاعدة البيانات أو جسم طلب مفقودًا. الحل: أضف فحصًا:
if result is None:
return {"error": "Not found"}, 404
أخطاء تطبيق الجوال
الخطأ Network request failed (على محاكي Android)
السبب: يستخدم محاكي Android العنوان 10.0.2.2 للوصول إلى جهازك المضيف، وليس localhost.
الحل: في App.tsx، اضبط:
const API_BASE_URL = 'http://10.0.2.2:5000';
الخطأ Network request failed (على جهاز حقيقي)
السبب: لا يستطيع الهاتف الوصول إلى حاسوبك.
الحل: استخدم عنوان IP المحلي لحاسوبك (وليس localhost):
# اعرف عنوان IP الخاص بك
ip addr show | grep inet # Linux
ifconfig # macOS
ipconfig # Windows
ثم حدّث API_BASE_URL وتأكد من أن الجهازين متصلان بشبكة WiFi نفسها.
خطأ CORS في السجلات
Access to fetch at 'http://localhost:5000' from origin 'http://localhost:8081' has been blocked by CORS policy
السبب: لا يسمح خادم Flask بالطلبات العابرة للمصادر القادمة من خادم تطوير Expo.
الحل: تأكد من تثبيت flask-cors وإعداده (انظر backend/step-06-cors.md).
الخطأ TypeError: undefined is not an object
السبب: حاولت الوصول إلى خاصية على قيمة undefined أو null.
الحل: تحقق من وجود المتغير قبل الوصول إليه:
if (data && data.messages) {
// يمكن الوصول إلى data.messages بأمان
}
الخطأ Can't find variable: fetch
السبب: تستخدم بيئة تشغيل JavaScript أقدم لا تتوفر فيها fetch.
الحل: ثبّت react-native-fetch-api أو حدّث Expo SDK؛ إذ يتضمن Expo Go الدالة fetch.
الخطأ Module "fs" has been externalized for browser compatibility
السبب: حاولت استخدام وحدة fs الخاصة بـ Node.js داخل تطبيق React Native.
الحل: لا تتوفر وحدة fs في React Native. اقرأ الملفات بطريقة مختلفة أو استخدم AsyncStorage.
أخطاء Git
الخطأ fatal: not a git repository
السبب: أنت في مجلد لم يُهيَّأ باستخدام git.
الحل: شغّل git init أولًا.
الخطأ fatal: remote origin already exists
السبب: لقد أضفت remote بالفعل. الحل: حدّثه بدلًا من ذلك:
git remote set-url origin https://github.com/user/repo.git
الخطأ CONFLICT (content): Merge conflict in file.py
السبب: غيّر فرعان السطر نفسه.
الحل: افتح الملف، وابحث عن العلامات <<<<<<< و======= و>>>>>>>، وحرّره بحيث تُبقي النسخة الصحيحة، ثم:
git add file.py
git commit -m "Resolve merge conflict"
ما زلت عالقًا؟
- ابحث في Google عن نص الخطأ حرفيًا — من المؤكد تقريبًا أن أحدًا واجه المشكلة نفسها
- راجع Stack Overflow — ابحث بنص الخطأ مع التقنية التي تستخدمها (مثل: "Flask sqlalchemy no such table")
- اسأل الذكاء الاصطناعي — الصق الخطأ كاملًا والكود ذا الصلة في ChatGPT أو Claude
- اسأل صديقًا — اشرح المشكلة بصوت عالٍ (غالبًا ما يكشف هذا وحده عن الإجابة)