حل خطأ 500 Internal Server Error بالعربي

أنت زائر تتصفح، أو صاحب موقع صحيت الصبح على تنبيهات، وأمامك:

500 Internal Server Error
The server encountered an internal error and was unable to
complete your request.

أغمض رسالة في الويب: لا تفاصيل، ولا سبب، ولا اتجاه. لكن هذا مقصود، والسبب الحقيقي مكتوب في مكان آخر يملكه صاحب الموقع.

معنى خطأ 500

500 Internal Server Error رمز حالة في بروتوكول HTTP معناه: طلبك وصل للخادم سليمًا، لكن الخادم فشل أثناء تنفيذه. هو أعمّ رمز في عائلة 5xx: يرسله الخادم عندما ينكسر شيء داخله ولا يوجد رمز أدق يصفه. فلا تقرأه كتشخيص، بل كجملة «شيء انكسر عندنا».

ولماذا لا تقول الصفحة ما انكسر؟ لأن تفاصيل العطل (مسارات الملفات، واستعلامات SQL، وأسطر الكود) كنز للمهاجمين. فالخادم يكتبها كاملة في سجلّه، ويُظهر للزائر رسالة عامة.

إن كنت زائرًا: ماذا تفعل؟

العطل عند الموقع لا عندك في الغالب الأعم، لكن جرّب هذه الثلاثة قبل أن تستسلم:

1. انتظر دقيقة ثم أعد التحميل. كثير من أعطال 500 لحظية: نشر تحديث، أو إعادة تشغيل، أو ضغط مؤقت.
2. جرّب نافذة خاصة (Incognito). نادرًا ما يكون السبب كوكي تالفًا لهذا الموقع ينهار الخادم عند قراءته. إن عمل الموقع في النافذة الخاصة، فاحذف كوكيز هذا الموقع وحده من إعدادات المتصفح.
3. إن ظهر في كل مكان، فلا شيء بيدك: انتظر، أو تابع حسابات الموقع الرسمية التي تعلن الأعطال عادة.

ورسالة «500. حدث خطأ. يُرجى إعادة المحاولة لاحقًا. ذلك كل ما نعرفه.» هي صفحة الخطأ العامة في خدمات Google (يوتيوب وGmail وغيرها). نفس المعنى: عطل في خوادم Google، لا في جهازك ولا في اشتراكك.

عائلة 5xx: اقرأ الرقم قبل أن تبحث

التفريق بين 500 و502 يوفّر ساعات: 500 يعني أن تطبيقك نفسه ردّ بالخطأ (أو خادم الويب انكسر عند تنفيذه)، أما 502 فيعني أن Nginx لم يجد تطبيقك أصلًا، فابحث عن سبب توقف العملية، لا عن سطر في الكود. وإن لم يصل الطلب لأي خادم إطلاقًا فهذا خطأ مختلف تمامًا: ERR_CONNECTION_REFUSED.

إن كنت صاحب الموقع: التشخيص في خمس خطوات

1. سجّل وقت الخطأ والمسار وطريقة الطلب (GET/POST) وأي request ID ظاهر. هذه المفاتيح توصلك إلى السطر الصحيح وسط آلاف السجلات.

2. أعد الطلب مرة واحدة من الطرفية لترى الحالة والرؤوس بلا واجهة التطبيق:

   نسخ

   curl -i https://example.com/path
   

3. افتح سجل التطبيق في اللحظة نفسها، ثم سجل Nginx/Apache أو منصة الاستضافة إن لم يظهر شيء. لا تكتفِ بأدوات المطوّر في المتصفح: هي ترى الرمز 500 فقط.

4. أصلح أول exception في السلسلة، لا آخر خمسة أخطاء نتجت عنه. ثم افحص متغيرات البيئة واتصال قاعدة البيانات والاعتماديات بين المحلي والإنتاج.

5. كرّر نفس الطلب وتأكد أنه يعيد الحالة الصحيحة، ثم راقب السجل فترة قصيرة حتى لا يكون العطل متقطعًا فقط.

القاعدة الذهبية: السجلات أولًا، لا التخمين

# خوادم Nginx / Apache على لينكس
sudo tail -50 /var/log/nginx/error.log
sudo tail -50 /var/log/apache2/error.log

# تطبيق يعمل كخدمة systemd (Node أو Python خلف Nginx)
sudo journalctl -u my-app --since "10 min ago"

# تطبيق داخل Docker
docker logs --tail 50 my-app

• منصات سحابية (Vercel وRailway وRender): تبويب Logs في لوحة المشروع، وغالبًا يمكنك تصفيته بالمسار أو بالحالة 500.
• استضافة مشتركة (cPanel): أيقونة Errors، أو ملف error_log داخل مجلد الموقع.

سطر الخطأ سيسمّي الملف والسبب حرفيًا، ومن هنا يبدأ كل حل حقيقي.

الأسباب الأشهر وعلاجها

1) Exception غير معالج في الكود

استعلام فشل، أو قيمة undefined فاجأت الكود، أو مكتبة رمت خطأ: أي استثناء يصعد بلا معالجة يصبح 500. السجل يعطيك الـ stack trace كاملًا، وأشهر سطر فيه عند مطوري JavaScript هو Cannot read properties of undefined. عالج الحالة، وأضف معالج أخطاء يردّ بحالة مناسبة ورسالة آمنة (القسم الأخير).

2) متغير بيئة ناقص بعد النشر

يعمل محليًا وينهار في الإنتاج؟ الفرق الأول دائمًا هو .env: مفتاح قاعدة البيانات أو الـ API غير مضبوط في بيئة الاستضافة، لأن ملف .env لا يُرفع مع الكود (وهذا صحيح). راجع إعدادات المتغيرات في لوحة منصتك وقارنها بقائمة مشروعك، وتذكّر أن تغييرها يحتاج إعادة نشر أو إعادة تشغيل غالبًا.

3) قاعدة البيانات لا تستجيب

بيانات اتصال خاطئة، أو خادم قاعدة متوقف، أو حد اتصالات ممتلئ. علامات مميزة في السجل: Connection refused أو Access denied أو too many connections. والثانية لها دليل كامل: حل خطأ Access denied في MySQL.

4) WordPress: الإضافة أو الثيم أو htaccess

أولًا، اجعل WordPress يكتب الخطأ الحقيقي في ملف بدل الصفحة البيضاء. أضف في wp-config.php قبل سطر «That's all, stop editing»:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // يكتب في wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // لا يعرض الأخطاء للزوار

افتح wp-content/debug.log وستجد اسم الإضافة أو الثيم في سطر الخطأ غالبًا. وإن لم يظهر شيء، فثالوث الـ 500 بعد أي تحديث:

• الإضافات: أعد تسمية مجلد wp-content/plugins مؤقتًا. رجع الموقع؟ أعد الاسم، وعطّل الإضافات واحدة واحدة حتى تجد المسبّبة.
• .htaccess تالف: أعد تسميته، وادخل الإعدادات ← الروابط الدائمة ← حفظ، ليتولّد ملف نظيف.
• حد الذاكرة: ارفع memory_limit من استضافتك، أو WP_MEMORY_LIMIT في wp-config.php.

وبعد الإصلاح، أعد WP_DEBUG إلى false.

5) Laravel وDjango: الخطأ مكتوب في مكانه المعتاد

• Laravel: السجل في storage/logs/laravel.log. أشهر سببين بعد نشر جديد: مفتاح التطبيق ناقص (No application encryption key has been specified، والحل php artisan key:generate ثم وضع القيمة في متغيرات الإنتاج)، ومجلدا storage وbootstrap/cache غير قابلين للكتابة من مستخدم خادم الويب.
• Django: مع DEBUG = False في الإنتاج يعرض للزائر Server Error (500) فقط، والتفاصيل في سجل Gunicorn أو الخدمة. لا تقلب DEBUG إلى True على خادم حي لتراها: هذا يعرض إعداداتك وأسرارك لكل من يزور الصفحة.

6) صلاحيات ملفات خاطئة على الخادم

رفعت ملفات بـ root، أو تغيّر مالك الملفات أثناء النشر؟ القيمتان 755 للمجلدات و644 للملفات إعدادان شائعان في استضافات Linux، لكنهما ليستا قاعدة تصلح لكل حاوية أو منصة. افحص المالك والمجموعة والمستخدم الذي يشغّل التطبيق، ولا تستخدم chmod -R 777 كحل سريع، لأنه يفتح صلاحيات لا يحتاجها التطبيق. وقصة الصلاحيات كاملة في حل Permission denied في لينكس.

للمطور: لا تدع 500 يصل المستخدم أعمى

في Express، معالج أخطاء واحد في آخر التطبيق يسجّل التفاصيل للسجل، ويردّ على المستخدم برسالة عامة:

const express = require("express");
const app = express();

app.get("/sync", (req, res) => {
  const user = undefined;
  res.send(user.name);                 // TypeError
});

app.get("/async", async (req, res) => {
  await Promise.resolve();
  throw new Error("db down");          // خطأ داخل دالة async
});

app.use((err, req, res, next) => {
  console.error(err);                                        // التفاصيل للسجل
  res.status(500).json({ error: "حدث خطأ — جرّب لاحقًا" });  // العموم بلا أسرار
});

app.listen(3000);

جرّبنا هذا الكود على إصدارين، وظهر فرق مهم:

Express 5 يلتقط أخطاء الدوال async ويمرّرها لمعالجك تلقائيًا. أما Express 4 فلا يراها، فيبقى المستخدم ينتظر حتى تنتهي المهلة. على Express 4، لفّ المعالج بـ try/catch ومرّر الخطأ بـ next(err)، أو انتقل لـ Express 5.

وفي Next.js، رسائل أخطاء مكوّنات الخادم تُخفى تلقائيًا في الإنتاج، ويصل للمتصفح رقم digest فقط تطابقه مع السجل. صفحة الخطأ نفسها تبنيها بملف error.tsx (درس التحميل والأخطاء في Next.js).

والواجهة الأمامية تتحقق من res.ok قبل قراءة الرد، وإلا انفجر عندها خطأ مضلل ثانٍ فوق الأول، لأن صفحة الخطأ HTML لا JSON: Unexpected token in JSON.

قائمة تحقّق سريعة

• زائر؟ ← أعد المحاولة بعد دقيقة، وجرّب نافذة خاصة، ثم انتظر.
• 500 أم 502؟ ← 500 في كود التطبيق، و502 تطبيق متوقف خلف Nginx.
• افتح السجل قبل أي تخمين: السبب مكتوب فيه حرفيًا.
• سجّل وقت الطلب ومساره وrequest ID لتطابق الخطأ مع السطر الصحيح.
• يعمل محليًا لا إنتاجًا؟ ← متغيرات البيئة أولًا.
• WordPress؟ ← WP_DEBUG_LOG، ثم الإضافات، ثم .htaccess، ثم الذاكرة.
• متقطع مع الضغط؟ ← الذاكرة واتصالات قاعدة البيانات.
• كمطور: معالج أخطاء يسجّل بالتفصيل ويردّ بالعموم، ويلتقط أخطاء async.

الخلاصة

خطأ 500 «صندوق أسود» للزائر فقط، أما لصاحبه فمفتوح بالكامل في السجلات. اقرأ الـ log، وسمِّ العطل، وعالج مصدره من القائمة أعلاه، ولا تشخّص من شكل الصفحة أبدًا.

افهم بروتوكول الويب ورموز الحالة من الجذور في درس HTTP ضمن مسار الشبكات بالعربي ومسار Node.js، وأكمل سلسلة أخطاء الخوادم مع حل خطأ 404 وحل خطأ CORS.