قاموس أخطاء Supabase بالعربي: معنى كل رمز وكيف تتأكد منه

يطلع لك خطأ من Supabase في Console أو على الشاشة، والرسالة بالإنجليزي، ومرات عامة ما تقول شي. هذي الصفحة قاموس لرموز الأخطاء اللي تطلع في المنتجات المبنية بـ Lovable و Bolt و v0 و Cursor على Supabase: إيش يعني كل رمز، وإيش أول شي تتأكد منه. الرموز مكتوبة بالإنجليزي كما يكتبها Supabase و PostgREST و Postgres، عشان تبحث عنها كما تشوفها.

رد الخطأ فيه ثلاث أشياء، اقرأها بهذا الترتيب:

1. رمز الحالة (HTTP status): رقم مثل 400 أو 401 أو 403 أو 429. يعطيك نوع المشكلة بشكل عام فقط.
2. الرمز (code): مثل invalid_credentials أو PGRST116 أو 23505. هذا اللي يحدد الخطأ بالضبط.
3. الرسالة (message): شرح للمطوّر بالإنجليزي، ومعها أحيانًا details و hint، وفيهم غالبًا أهم معلومة.

اعتمد على الرمز، مو على نص الرسالة. Supabase ينصح تتعرّف على الخطأ من error.code، ولا تعتمد على رمز الحالة وحده لأنه ممكن يتغير. و Postgres يقول نفس الشي عن رموزه: النص يتغير بين الإصدارات ومع الترجمة، والرمز ثابت.

كيف تلقى رمز الخطأ

• من المتصفح: افتح منتجك، واضغط F12، وافتح تبويب Network، وسوّ الحركة اللي تفشل. اختار الطلب الأحمر وافتح Response: الرمز في code أو error_code.
• من رابط الطلب: الرابط يقول لك أي خدمة ردّت. /auth/v1/ للتسجيل والدخول، و /rest/v1/ لقاعدة البيانات، و /storage/v1/ للملفات، و /functions/v1/ للـ Edge Functions.
• من الكود: في supabase-js الخطأ يرجع في error. اطبعه كامل في Console، مو error.message فقط، عشان يبان error.code.
• من سجلات Supabase: في لوحة Supabase افتح Logs، واختار الخدمة من Log Type، مثل Auth أو PostgREST أو Postgres أو Edge Function. فلتر Status يقبل رمز HTTP أو رمز Postgres مثل 42501.
• في Edge Functions: رمز المنصة يجي في ترويسة اسمها sb-error-code. تلقاها في Headers داخل نفس الطلب في Network.

رموز أخطاء Supabase Auth

هذي الرموز ترجع من /auth/v1/: التسجيل والدخول والجلسات والإيميلات. في Network تلقى الرمز في error_code أو code داخل Response، وفي supabase-js في error.code. ورمز الحالة يعطيك فكرة سريعة:

• 403: ميزة مو متاحة لهذا المستخدم، والكود طلبها بدون ما يتأكد قبل.
• 422: الطلب وصل، لكن حالة المستخدم أو خدمة Auth ما تسمح بتنفيذه.
• 429: الطلب تجاوز حد من الحدود. لازم الكود يتعامل معه، خصوصًا في التسجيل والدخول.
• 500: خدمة Auth متعطّلة، وغالبًا السبب في قاعدة بياناتك، مثل trigger أو دالة فيها خطأ.
• 501: الميزة مو مفعّلة في خدمة Auth، والكود يستخدمها.

التسجيل والدخول

• invalid_credentials: بيانات الدخول أو نوع الدخول غير معروف. تتأكد من: إن المستخدم موجود في Authentication > Users وإنه سجّل بالإيميل وكلمة المرور، مو بـ Google مثلًا.
• email_not_confirmed: الدخول ممنوع لأن الإيميل ما تأكد. تتأكد من: إن إيميل التأكيد وصل فعلًا للمستخدم. الشرح الكامل في Email not confirmed.
• phone_not_confirmed: الدخول ممنوع لأن رقم الجوال ما تأكد. تتأكد من: إن رسالة التأكيد وصلت للرقم نفسه.
• user_already_exists: فيه مستخدم بنفس الإيميل أو الرقم، وما ينفع ينشأ مرة ثانية. تتأكد من: إن الواجهة توجّه المستخدم لتسجيل الدخول بدل ما توقف عند الخطأ.
• email_exists: الإيميل موجود في النظام. تتأكد من: إن المستخدم ما سجّل قبل بطريقة ثانية.
• phone_exists: رقم الجوال موجود في النظام. تتأكد من: إن الرقم ما انربط قبل بحساب ثاني.
• weak_password: كلمة المرور ما تحقق شروط القوة. تتأكد من: إن الواجهة تعرض الأسباب اللي ترجع مع الخطأ، مو رسالة عامة.
• same_password: كلمة المرور الجديدة نفس الحالية. تتأكد من: إن نموذج التغيير يطلب كلمة مختلفة.
• signup_disabled: إنشاء حسابات جديدة مقفل في الإعدادات. تتأكد من: إعداد السماح بالتسجيل في Auth، إذا القفل مو مقصود.
• email_provider_disabled: التسجيل بالإيميل وكلمة المرور مقفل. تتأكد من: إن مزوّد Email مفعّل في إعدادات Auth.
• phone_provider_disabled: التسجيل بالجوال وكلمة المرور مقفل. تتأكد من: إن مزوّد Phone مفعّل في إعدادات Auth.
• anonymous_provider_disabled: الدخول كزائر مجهول (anonymous sign-in) مقفل. تتأكد من: إن الكود فعلًا يحتاج signInAnonymously، وإذا يحتاجه فعّله.
• email_address_invalid: Supabase ما يقبل نطاقات الأمثلة والتجربة. تتأكد من: إنك تجرّب بإيميل حقيقي، مو عنوان على example.com.
• email_address_not_authorized: الإرسال ممنوع لهذا الإيميل لأن مشروعك على خدمة الإيميل الافتراضية، وهي ترسل لأعضاء منظمتك في Supabase فقط. تتأكد من: إنك ربطت مزوّد إيميل خاص (custom SMTP) قبل الإطلاق. الشرح الكامل في Email not confirmed.
• user_banned: المستخدم محظور، وحقل banned_until عنده للحين ساري. تتأكد من: قيمة banned_until للمستخدم في جدول auth.users.
• user_not_found: المستخدم ما عاد موجود. تتأكد من: إن الحساب ما انحذف من Authentication > Users.
• validation_failed: البيانات المرسلة مو بالصيغة المطلوبة. تتأكد من: شكل الإيميل أو الرقم في Payload داخل Network.
• bad_json: جسم الطلب مو JSON صحيح. تتأكد من: Payload في Network، هل فيه JSON كامل؟
• captcha_failed: Supabase ما قدر يتحقق من CAPTCHA عند مزوّدها. تتأكد من: إن مفتاح CAPTCHA في إعدادات Auth من نفس الحساب اللي فيه مفتاح الواجهة.

الإيميلات والرموز المؤقتة والحدود

• over_email_send_rate_limit: انرسلت إيميلات كثيرة لهذا العنوان. تتأكد من: إن زر إعادة الإرسال عليه مهلة، وإنك على مزوّد إيميل حقيقي. الشرح الكامل في email rate limit exceeded.
• over_sms_send_rate_limit: انرسلت رسائل SMS كثيرة لهذا الرقم. تتأكد من: إن زر إعادة الإرسال عليه مهلة.
• over_request_rate_limit: طلبات كثيرة من نفس العميل (عنوان IP)، ومرات السبب خطأ في الكود يرسل طلبات بدون توقف، مثل useEffect مكتوب غلط. تتأكد من: عدد طلبات /auth/v1/ في Network وأنت ما تسوي شي.
• otp_expired: الرمز المؤقت أو رابط الدخول انتهت مدته. تتأكد من: إن المستخدم يفتح آخر رابط وصله ويسجّل من جديد.
• otp_disabled: الدخول بالرمز المؤقت (magic link أو رمز بالإيميل) مقفل. تتأكد من: إعدادات الدخول بالإيميل في Auth.
• sms_send_failed: إرسال SMS فشل. تتأكد من: إعدادات مزوّد SMS في Auth.
• invite_not_found: الدعوة انتهت أو انستخدمت. تتأكد من: إنك ترسل دعوة جديدة بدل الرابط القديم.
• reauthentication_needed: المستخدم لازم يأكد هويته مرة ثانية قبل ما يغيّر كلمة المرور. تتأكد من: إن الكود يستدعي supabase.auth.reauthenticate() قبل التغيير.
• reauthentication_not_valid: رمز تأكيد الهوية غلط. تتأكد من: إن المستخدم يدخل رمز جديد.

الجلسات والتوكن

• refresh_token_not_found: الجلسة اللي فيها الـ refresh token ما انلقت. تتأكد من: إن ما فيه كود يسجّل خروج أو يمسح الجلسة قبل التجديد. الشرح الكامل في Invalid Refresh Token.
• refresh_token_already_used: الـ refresh token انلغى، وطلع برا المدة المسموحة لإعادة استخدامه. تتأكد من: إن الجلسة تتجدّد من مكان واحد في الكود، مو من مكانين في نفس اللحظة. الشرح الكامل في Invalid Refresh Token.
• session_expired: الجلسة انتهت، لأن المستخدم ترك المنتج مدة الخمول المحددة، أو لأن الجلسة تجاوزت أقصى عمر لها في الإعدادات. تتأكد من: إعدادات الجلسات في Auth، وإن الواجهة ترجع المستخدم لصفحة الدخول.
• session_not_found: الجلسة ما عادت موجودة، مثل بعد تسجيل الخروج. تتأكد من: إن الكود ما يستخدم جلسة قديمة بعد signOut.
• conflict: تعارض في قاعدة البيانات، وغالبًا من طلبات تجديد جلسة كثيرة لنفس المستخدم في نفس اللحظة. تتأكد من: إن التجديد يصير من مكان واحد، وإن إعادة المحاولة تنتظر وقت يزيد كل مرة.
• bad_jwt: الـ JWT في ترويسة Authorization مو صالح. تتأكد من: إن الطلب يرسل توكن جلسة المستخدم نفسه، مو نص فاضي أو قيمة ثانية.
• no_authorization: الطلب يحتاج ترويسة Authorization وما انرسلت. تتأكد من: إن الطلب ينرسل بعد ما تجهز جلسة المستخدم.
• not_admin: المستخدم مو مدير لخدمة Auth، والـ JWT ما فيه دور يعطيه هذي الصلاحية. تتأكد من: إن دوال auth.admin تشتغل في السيرفر بمفتاح service_role، مو في المتصفح.
• insufficient_aal: الطلب يحتاج مستوى تحقق أعلى، يعني المستخدم لازم يحل تحدي MFA. تتأكد من: إن الواجهة تطلب رمز MFA قبل هذي الخطوة.
• request_timeout: الطلب أخذ وقت طويل. تتأكد من: إن الكود يعيد الطلب، وإذا تكرر شوف سجلات Auth.
• unexpected_failure: خدمة Auth متعطّلة أو فيها خطأ بدون سبب محدد. تتأكد من: سجلات Auth، وأي trigger يشتغل لما ينشأ مستخدم جديد.
• unexpected_audience: ميزة قديمة ما تستخدمها مكتبات Supabase: قيمة X-JWT-AUD ما تطابق audience الـ JWT. تتأكد من: إن ما فيه كود قديم يرسل هذي الترويسة.

الدخول بـ Google وغيره (OAuth) وربط الحسابات

• provider_disabled: مزوّد OAuth مقفل. تتأكد من: إن المزوّد، مثل Google، مفعّل في إعدادات Auth ومعه مفاتيحه.
• oauth_provider_not_supported: الكود يستخدم مزوّد OAuth مقفل في خدمة Auth. تتأكد من: اسم المزوّد في الكود، وإنه مفعّل في الإعدادات.
• bad_oauth_callback: رجوع المزوّد إلى Supabase ناقص فيه state. تتأكد من: ربط المزوّد بـ Supabase ومكتبة Supabase اللي يستخدمها المنتج.
• bad_oauth_state: قيمة state اللي رجّعها المزوّد مو بالصيغة الصحيحة. تتأكد من: إعدادات ربط المزوّد بـ Supabase.
• provider_email_needs_verification: بعض مزوّدي OAuth ما يتأكدون من الإيميل، و Supabase يحتاجه مؤكد، فيرسل إيميل تأكيد بعد الدخول. تتأكد من: إن الواجهة تقول للمستخدم يفتح إيميله.
• bad_code_verifier: في تدفق PKCE، الـ code verifier ما يطابق المتوقع، و Supabase يقول إن السبب غالبًا خطأ في تطبيق المكتبة. تتأكد من: إن مكتبة Supabase في المنتج محدّثة.
• flow_state_expired: حالة تدفق PKCE انتهت مدتها. تتأكد من: إن الواجهة تطلب من المستخدم يسجّل دخول من جديد.
• flow_state_not_found: حالة تدفق PKCE ما عادت موجودة، ومرات السبب إعادة نفس الطلب، لأن الطلب الأول مسحها. تتأكد من: إن صفحة الرجوع (callback) ترسل الرمز مرة وحدة فقط.
• identity_already_exists: الهوية مربوطة بمستخدم. تتأكد من: إن الحساب الخارجي، مثل حساب Google، ما انربط قبل بمستخدم ثاني في منتجك.
• identity_not_found: الهوية ما عادت موجودة، مثل بعد فك ربطها أو حذفها. تتأكد من: إن الواجهة ما تعرض هوية انفك ربطها.
• manual_linking_disabled: ربط الهويات يدويًا بـ supabase.auth.linkUser() والدوال المشابهة مو مفعّل. تتأكد من: خيار الربط اليدوي في إعدادات Auth.
• single_identity_not_deletable: ما ينفع تفك آخر هوية مربوطة بالمستخدم، لأن كل مستخدم لازم يكون له هوية وحدة على الأقل. تتأكد من: إن الواجهة تخفي زر فك الربط لما تكون الهوية وحيدة.
• email_conflict_identity_not_deletable: فك هذي الهوية يغيّر إيميل الحساب لإيميل يستخدمه حساب ثاني. تتأكد من: هل المستخدم عنده حسابين بإيميلين مختلفين، وإذا عنده انقل بياناته لواحد منهم.

التحقق بخطوتين (MFA)

• mfa_verification_failed: رمز MFA غلط. تتأكد من: إن وقت جوال المستخدم مضبوط، لأن رموز TOTP تعتمد على الوقت.
• mfa_challenge_expired: الرد على تحدي MFA تأخر عن المدة المحددة. تتأكد من: إن الواجهة تطلب تحدي جديد بدل ما تعيد القديم.
• mfa_factor_not_found: عامل MFA ما عاد موجود. تتأكد من: قائمة العوامل الحالية للمستخدم قبل التحقق.
• mfa_factor_name_conflict: عاملين MFA لنفس المستخدم لهم نفس الاسم. تتأكد من: إن كل عامل له اسم مختلف.
• mfa_ip_address_mismatch: تسجيل عامل MFA لازم يبدأ وينتهي من نفس عنوان IP. تتأكد من: إن المستخدم ما غيّر الشبكة في نص التسجيل، مثل من Wi-Fi إلى بيانات الجوال.
• mfa_verified_factor_exists: المستخدم عنده عامل جوال مؤكد. تتأكد من: إنك تلغي العامل الحالي قبل تسجيل واحد جديد.
• too_many_enrolled_mfa_factors: المستخدم وصل الحد الأقصى لعوامل MFA. تتأكد من: إن العوامل القديمة اللي ما تأكدت تنحذف.
• mfa_verification_rejected: التحقق انرفض، وهذا يطلع فقط إذا عندك hook للتحقق من MFA ورجّع رفض. تتأكد من: منطق الـ hook وسجلاته.
• mfa_totp_enroll_not_enabled: تسجيل عوامل TOTP مقفل. تتأكد من: إعدادات MFA في Auth.
• mfa_totp_verify_not_enabled: الدخول والتحقق بعوامل TOTP مقفل. تتأكد من: إعدادات MFA في Auth.
• mfa_phone_enroll_not_enabled: تسجيل عوامل الجوال مقفل. تتأكد من: إعدادات MFA في Auth.
• mfa_phone_verify_not_enabled: الدخول والتحقق بعوامل الجوال مقفل. تتأكد من: إعدادات MFA في Auth.
• mfa_web_authn_enroll_not_enabled: تسجيل عوامل WebAuthn مقفل. تتأكد من: إعدادات MFA في Auth.
• mfa_web_authn_verify_not_enabled: الدخول والتحقق بعوامل WebAuthn مقفل. تتأكد من: إعدادات MFA في Auth.

دخول الشركات (SSO و SAML)

• saml_provider_disabled: الدخول بـ SAML 2.0 مو مفعّل. تتأكد من: إن Enterprise SSO مفعّل في مشروعك.
• sso_provider_not_found: مزوّد SSO ما انلقى. تتأكد من: القيم اللي ترسلها لـ supabase.auth.signInWithSSO().
• saml_idp_not_found: مزوّد هوية SAML ما انلقى، وغالبًا بعد دخول بدأ من مزوّد غير مسجّل في Supabase. تتأكد من: إن مزوّد الشركة مسجّل في مشروعك.
• saml_assertion_no_email: بيانات المستخدم وصلت من SAML بدون إيميل، والإيميل مطلوب. تتأكد من: ربط الحقول (attribute mapping) عند مزوّد الشركة.
• saml_assertion_no_user_id: بيانات المستخدم وصلت من SAML بدون رقم المستخدم (NameID). تتأكد من: إعدادات مزوّد الشركة.
• saml_relay_state_expired: مزوّد SAML تأخر في الرد على الدخول. تتأكد من: إن الواجهة تطلب من المستخدم يسجّل من جديد.
• saml_relay_state_not_found: حالة الدخول انمسحت بعد ما انتهت. تتأكد من: إن الواجهة تطلب من المستخدم يسجّل من جديد.
• saml_metadata_fetch_failed: إضافة أو تعديل مزوّد SAML فشل لأن بياناته ما انجابت من الرابط. تتأكد من: إن رابط الـ metadata يفتح من برا شبكة الشركة.
• saml_entity_id_mismatch: الـ entity ID في التعديل ما يطابق المحفوظ. تتأكد من: إنك تضيف مزوّد جديد بدل ما تعدّل القديم، وهذا اللي ينصح فيه Supabase.
• saml_idp_already_exists: مزوّد SAML هذا مضاف قبل. تتأكد من: قائمة المزوّدين قبل الإضافة.
• sso_domain_already_exists: النطاق مسجّل لمزوّد SSO ثاني، وكل نطاق يتسجّل مرة وحدة. تتأكد من: إن النطاق مو مربوط بمزوّد قديم.
• user_sso_managed: المستخدم جاي من SSO، وبعض بياناته مثل الإيميل ما تتعدّل. تتأكد من: إن الواجهة تخفي تعديل الإيميل لهؤلاء المستخدمين.

Auth Hooks

• hook_timeout: خدمة Auth ما وصلت للـ hook في الوقت المحدد. تتأكد من: سرعة الدالة أو الرابط اللي ربطته كـ hook.
• hook_timeout_after_retry: ما وصلت للـ hook بعد كل المحاولات. تتأكد من: إن الـ hook شغّال ويرد.
• hook_payload_over_size_limit: البيانات اللي ترسلها Auth للـ hook أكبر من الحد. تتأكد من: حجم البيانات اللي يضيفها الـ hook أو يتوقعها.
• hook_payload_invalid_content_type: البيانات من Auth ما فيها ترويسة Content-Type صحيحة. تتأكد من: إعدادات الـ hook وطريقة قراءته للطلب.

أخطاء Data API: رموز PGRST

لما الكود يقرأ أو يكتب في الجداول عن طريق supabase-js، الطلب يروح لـ /rest/v1/، وهذا Data API اللي يشغّله PostgREST. أي رمز يبدأ بـ PGRST جاي من PostgREST نفسه، وأي رمز من خمس خانات مثل 42501 جاي من Postgres ويمر كما هو. الرقم بين القوسين رمز الحالة اللي يرجع معه. الرموز هنا حسب توثيق PostgREST الحالي، والمشاريع القديمة ممكن ترجع رمز مختلف لنفس المشكلة.

الاتصال بقاعدة البيانات

• PGRST000 (503): PostgREST ما قدر يتصل بقاعدة البيانات، لأن رابط الاتصال غلط أو Postgres مو شغّال. تتأكد من: حالة المشروع في لوحة Supabase.
• PGRST001 (503): الاتصال بقاعدة البيانات فشل بسبب خطأ داخلي. تتأكد من: سجلات PostgREST و Postgres في Logs.
• PGRST002 (503): ما قدر يتصل بقاعدة البيانات وهو يبني الـ schema cache. تتأكد من: إن Postgres شغّال، وجرّب الطلب بعد دقيقة.
• PGRST003 (504): الطلب انتظر اتصال فاضي حتى انتهى الوقت. تتأكد من: الاستعلامات البطيئة اللي ماسكة الاتصالات وقت الزحمة.

صيغة الطلب

• PGRST100 (400): خطأ في قراءة معاملات الرابط: الفلاتر أو الترتيب. تتأكد من: كتابة .or() و .order() و select في الكود، مثل قوس ناقص أو فاصلة زايدة.
• PGRST102 (400): جسم الطلب غلط، مثل فاضي أو JSON مكسور. تتأكد من: Payload في Network.
• PGRST103 (416): المدى المطلوب للصفحات غير صحيح. تتأكد من: أرقام .range() في الكود، وإن البداية ما تتجاوز عدد السطور.
• PGRST106 (406): الـ schema المطلوب مو ضمن الـ schemas المكشوفة للـ API. تتأكد من: إن الـ schema مضاف في Exposed schemas في إعدادات API، إذا الكود يستخدم schema غير public.
• PGRST108 (400): فلتر على جدول مرتبط مو موجود في select. تتأكد من: إن الجدول اللي تفلتر عليه مكتوب في select نفس الطلب.
• PGRST116 (406): الكود طلب سطر واحد بـ .single()، والنتيجة صفر سطور أو أكثر من سطر. تتأكد من: عدد السطور في details. الشرح الكامل في JSON object requested, multiple (or no) rows returned.
• PGRST118 (400): ترتيب النتيجة بعمود من جدول مرتبط ما ينفع، لأن العلاقة بينهم مو many-to-one ولا one-to-one. تتأكد من: نوع العلاقة بين الجدولين.
• PGRST120 (400): الجدول المرتبط يتفلتر بـ is.null أو not.is.null فقط. تتأكد من: الفلتر اللي على الجدول المرتبط في الكود.
• PGRST125 (404): مسار غير صحيح في رابط الطلب. تتأكد من: رابط Supabase في متغيرات البيئة، وإنه بدون مسار زايد في آخره.

الـ schema cache: الجداول والعلاقات والدوال

PostgREST يحفظ عنده نسخة من شكل قاعدة البيانات: الجداول والأعمدة والعلاقات والدوال، واسمها schema cache. إذا غيّرت الجداول والنسخة ما تحدّثت، أو الشي فعلًا ناقص، تطلع هذي الرموز. حسب توثيق PostgREST أغلبها ينحل بإعادة تحميل النسخة، بالأمر NOTIFY pgrst, 'reload schema' في SQL Editor. لكن تأكد قبل إن الشي موجود فعلًا في قاعدة البيانات المنشورة.

• PGRST200 (400): العلاقة بين الجدولين ما انلقت: المفتاح الأجنبي قديم في النسخة، أو الجدول أو العلاقة نفسها مو موجودة. تتأكد من: إن فيه foreign key فعلي بين الجدولين في قاعدة البيانات المنشورة.
• PGRST201 (300): طلب ربط غامض، لأن بين الجدولين أكثر من علاقة. تتأكد من: إنك تحدد العلاقة باسم المفتاح الأجنبي بعد ! في select.
• PGRST202 (404): الدالة اللي يناديها .rpc() ما انلقت: توقيعها قديم في النسخة، أو الدالة مو موجودة. تتأكد من: اسم الدالة وأسماء معاملاتها في الكود، وإنها نفس اللي في قاعدة البيانات.
• PGRST203 (300): فيه أكثر من دالة بنفس الاسم ونفس أسماء المعاملات بأنواع مختلفة. تتأكد من: إن ما فيه نسخة قديمة من الدالة باقية. الحل حسب PostgREST: غيّر اسم الدالة أو أسماء معاملاتها.
• PGRST204 (400): عمود في الطلب ما انلقى. تتأكد من: إن اسم العمود في الكود موجود في الجدول المنشور بنفس الكتابة.
• PGRST205 (404): الجدول اللي في الرابط ما انلقى. تتأكد من: إن الجدول موجود في المشروع المنشور، مو في مشروع التجربة فقط. الشرح الكامل في relation does not exist.

JWT

• PGRST301 (401): الـ JWT ما انقرأ أو مو صالح. تتأكد من: إن ترويسة Authorization فيها توكن جلسة من نفس المشروع.
• PGRST302 (401): طلب بدون Bearer، والدخول كمجهول مقفل. تتأكد من: إن الطلب ينرسل بعد ما تجهز الجلسة.
• PGRST303 (401): التحقق من claims في الـ JWT فشل، ومن اللي يتحقق منه PostgREST وقت انتهاء التوكن (exp). تتأكد من: إن المنتج يجدّد الجلسة قبل ما يرسل الطلب. الشرح الكامل في JWT expired.

رموز Postgres اللي تطلع من Supabase

الرموز اللي من خمس خانات، مثل 23505، رموز Postgres نفسه (SQLSTATE)، وتمر عليك من /rest/v1/ أو من أي اتصال مباشر بقاعدة البيانات. الاسم الإنجليزي جنب كل رمز هو اسمه في توثيق Postgres، والرقم بين القوسين رمز الحالة اللي يحوّله له PostgREST.

الصلاحيات و RLS

• 42501 insufficient_privilege (403 للمستخدم المسجّل، و 401 للزائر): ما فيه صلاحية. يطلع برسالة permission denied for table لما الدور ما عنده صلاحية على الجدول، وبرسالة new row violates row-level security policy لما قاعدة RLS ترفض السطر. تتأكد من: هل الطلب راح كمستخدم مسجّل ولا كزائر. الشرح الكامل في permission denied for table و new row violates row-level security policy.
• 42P17 invalid_object_definition (500): PostgREST يسمّيه infinite recursion، وفي Supabase يطلع غالبًا برسالة infinite recursion detected in policy، يعني قاعدة RLS تقرأ من جدول قاعدته ترجع لها. تتأكد من: إن قاعدة RLS على الجدول ما تستعلم من نفس الجدول.

جداول وأعمدة ودوال ناقصة

• 42P01 undefined_table (404): الجدول مو موجود، برسالة relation "..." does not exist. تتأكد من: إن تغييرات قاعدة البيانات (migrations) انطبقت على المشروع المنشور. الشرح الكامل في relation does not exist.
• 42703 undefined_column (400): العمود مو موجود. تتأكد من: اسم العمود في الكود وفي الجدول المنشور.
• 42883 undefined_function (404): الدالة مو موجودة بهذي الأنواع من المعاملات. تتأكد من: أنواع القيم اللي ترسلها للدالة، مثل نص بدل رقم.

قيود البيانات

• 23505 unique_violation (409): قيمة مكررة في عمود ممنوع فيه التكرار، برسالة duplicate key value violates unique constraint. تتأكد من: details، فيه اسم العمود والقيمة المكررة.
• 23503 foreign_key_violation (409): السطر يشير لسطر مو موجود في جدول ثاني، أو تحذف سطر تعتمد عليه سطور ثانية. تتأكد من: إن السطر الأصلي موجود قبل الإضافة، مثل سطر المستخدم قبل طلباته.
• 23502 not_null_violation (400): عمود إجباري وصله فاضي (null). تتأكد من: إن الكود يرسل القيمة، مثل user_id، أو إن للعمود قيمة افتراضية.
• 23514 check_violation (400): القيمة ما تحقق شرط CHECK على العمود. تتأكد من: الشرط المكتوب على العمود والقيمة اللي أرسلها الكود.
• 22P02 invalid_text_representation (400): القيمة ما تنفع لنوع العمود، مثل نص مو uuid في عمود uuid، والرسالة تبدأ بـ invalid input syntax for type. تتأكد من: قيمة الفلتر في رابط الطلب، مثل eq.undefined بدل رقم المستخدم.
• P0001 raise_exception (400): خطأ رفعته دالة أو trigger في قاعدة بياناتك بالأمر RAISE. تتأكد من: الدالة أو الـ trigger اللي على الجدول، والرسالة اللي فيها.

الوقت والاتصالات

• 57014 query_canceled (500): الاستعلام انلغى. من Supabase يطلع غالبًا برسالة canceling statement due to statement timeout، لأن لكل دور حد زمني: anon 3 ثواني، و authenticated 8 ثواني. تتأكد من: الاستعلام البطيء في Query Performance داخل Advisors.
• 53300 too_many_connections (503): قاعدة البيانات وصلت حد الاتصالات ورفضت الجديد. تتأكد من: إن السيرفر يتصل عن طريق الـ pooler، مو اتصال مباشر من كل طلب. الشرح الكامل في too many connections.

رموز أخطاء Supabase Storage

أخطاء الملفات ترجع من /storage/v1/، والرمز في جسم الرد مع message. Supabase للحين ينقل Storage لنظام رموز جديد، فممكن تشوف الرموز القديمة اللي تحت القائمة. وانتبه: لما الملف أو الـ bucket «مو موجود»، ممكن يكون موجود وما عندك صلاحية عليه.

• NoSuchBucket (404): الـ bucket مو موجود، أو موجود وما عندك صلاحية عليه. تتأكد من: اسم الـ bucket في الكود بنفس الحروف.
• NoSuchKey (404): الملف مو موجود، أو موجود وما عندك صلاحية عليه. تتأكد من: المسار الكامل للملف مع اسم المجلد.
• AccessDenied (403): الوصول للملف مرفوض. تتأكد من: إن فيه قاعدة RLS تسمح بهذي العملية على storage.objects. الشرح الكامل في new row violates row-level security policy.
• InvalidJWT (401): التوكن منتهي أو مكسور. تتأكد من: إن الجلسة متجدّدة قبل الرفع. الشرح الكامل في JWT expired.
• EntityTooLarge (413): الملف أكبر من الحد المسموح. تتأكد من: حد حجم الملفات في إعدادات المشروع.
• InvalidMimeType (400): نوع الملف (MIME type) غير صحيح. تتأكد من: إن contentType بالصيغة القياسية، مثل image/png.
• KeyAlreadyExists (409): ملف بنفس المسار موجود. تتأكد من: إنك فعلًا تبي تستبدله، وإذا تبي، أرسل الرفع مع upsert: true.
• ResourceAlreadyExists (409): الشي اللي تنشئه موجود. تتأكد من: الاسم، أو استخدم upsert: true إذا تبي تستبدل الملف.
• BucketAlreadyExists (409): فيه bucket بنفس الاسم. تتأكد من: إن الكود ما ينشئ الـ bucket كل مرة يشتغل.
• InvalidBucketName (400): اسم الـ bucket فيه حروف مو مسموحة. تتأكد من: الاسم حسب قواعد التسمية.
• InvalidKey (400): اسم الملف أو مساره غير صحيح. تتأكد من: اسم الملف كما ينرسل، والأسلم تسميه بحروف إنجليزية وأرقام بدل الاسم الأصلي.
• InvalidRange (416): المدى المطلوب من الملف غير صحيح. تتأكد من: إن المدى داخل حجم الملف.
• InvalidRequest (400): الطلب مو بالشكل المطلوب. تتأكد من: نص message، فيه التفاصيل.
• MissingParameter (400): معامل مطلوب ناقص. تتأكد من: نص message، فيه اسم المعامل.
• MissingContentLength (411): ترويسة Content-Length ناقصة. تتأكد من: إن الرفع ينرسل بالمكتبة، أو مع هذي الترويسة إذا ترفع بطلب يدوي.
• ResourceLocked (423): الملف مقفل وما يتعدّل وهو مقفل. تتأكد من: إن الكود ينتظر ويعيد المحاولة.
• LockTimeout (423): انتهى الوقت وهو ينتظر القفل. تتأكد من: إن الكود ينتظر ويعيد المحاولة.
• SlowDown (503): الطلبات كثيرة، و Storage بدأ يبطّئها. تتأكد من: إن الرفع ما يتكرر في حلقة، وإن إعادة المحاولة تنتظر وقت يزيد كل مرة.
• DatabaseTimeout (504): انتهى الوقت وهو يوصل لقاعدة البيانات. تتأكد من: أداء قاعدة البيانات وحجم الـ pool.
• DatabaseError (500): خطأ في قاعدة البيانات. تتأكد من: سجلات Postgres في Logs.
• InternalError (500): خطأ داخلي في الخادم. تتأكد من: سجلات Storage في Logs، وإذا السبب من Storage نفسه تواصل مع دعم Supabase.
• TenantNotFound (404): خدمة Storage ما انجهزت صح لمشروعك. تتأكد من: إن الخطأ يتكرر، وإذا تكرر تواصل مع دعم Supabase.

والرموز القديمة:

• not_found (404): الملف مو موجود أو ما عندك صلاحية عليه. تتأكد من: قاعدة RLS، وإن الطلب يرسل ترويسة Authorization للمستخدم.
• already_exists (409): الملف موجود. تتأكد من: إنك تستخدم upsert إذا تبي تستبدله.
• unauthorized (403): ما عندك صلاحية لهذا الطلب. تتأكد من: قاعدة RLS وترويسة Authorization.
• database_timeout (544): مستخدمين كثير يستخدمون Storage في نفس الوقت، و Postgres ما عنده اتصالات كافية. تتأكد من: حجم الـ pool وحجم المشروع.
• internal_server_error (500): خطأ ما انعالج. تتأكد من: إنك ترفع تذكرة لدعم Supabase.

رموز أخطاء Supabase Edge Functions

لما Edge Function تفشل، supabase-js يعطيك رسالة عامة: Edge Function returned a non-2xx status code. الرمز الحقيقي يجي في ترويسة sb-error-code في رد الطلب. الشرح الكامل للرسالة العامة في Edge Function returned a non-2xx status code.

أخطاء في كود الدالة

• EDGE_FUNCTION_ERROR: الدالة رمت خطأ ما انعالج، أو رجّعت رمز 5XX. تتأكد من: إن كود الدالة داخل try-catch ويرجع رد خطأ واضح. الشرح الكامل في Edge Function returned a non-2xx status code.
• WORKER_ERROR: الدالة رمت خطأ ما انعالج برا معالج الطلب. تتأكد من: سجلات الدالة، وأي كود يشتغل أول ما تبدأ الدالة.
• IDLE_TIMEOUT: الدالة ما ردّت خلال الحد الزمني. تتأكد من: استعلام بطيء أو طلب لخدمة خارجية بدون حد زمني.
• WORKER_RESOURCE_LIMIT أو WORKER_LIMIT: الدالة توقفت لأنها تجاوزت حد من حدود الموارد: الذاكرة أو وقت المعالج أو العمليات المتزامنة. تتأكد من: سجلات الدالة، فيها أي حد تجاوزته.
• INVALID_RESPONSE_STATUS_CODE: الدالة رجّعت رمز حالة غير صحيح، مو 101 وبرا المدى 200 إلى 599. تتأكد من: إن الدالة ما ترجّع رد خدمة خارجية كما هو، وتبني رد جديد بدلها.

أخطاء التوكن

• UNAUTHORIZED_NO_AUTH_HEADER: التحقق من JWT مفعّل، والطلب ما فيه ترويسة Authorization ولا apikey. تتأكد من: إن الكود يستدعي الدالة بـ supabase.functions.invoke، أو اقفل التحقق إذا الدالة webhook أو عامة.
• UNAUTHORIZED_ASYMMETRIC_JWT: التوكن في Authorization من نوع ES256 أو RS256 ومو صالح. تتأكد من: إن توكن المستخدم ما انتهى.
• UNAUTHORIZED_LEGACY_JWT: التوكن في Authorization من النوع القديم HS256 ومو صالح. تتأكد من: إن التوكن ما انتهى، وإن الـ JWT secret القديم ما انلغى.
• UNAUTHORIZED_UNSUPPORTED_TOKEN_ALGORITHM: التوكن مو ES256 ولا RS256 ولا HS256. تتأكد من: إنك ترسل توكن صادر من Supabase.
• UNAUTHORIZED_INVALID_JWT_FORMAT: ترويسة Authorization مو بصيغة Bearer <JWT Token>. تتأكد من: كلمة Bearer قبل التوكن، وإن مفتاح API ينرسل في apikey مو في Authorization.

أخطاء في طريقة الاستدعاء

• RATE_LIMIT_EXCEEDED: المنصة لاحظت دوال تنادي بعضها، أو دالة تنادي نفسها. تتأكد من: إن ما فيه دالة تنادي دالة ثانية في حلقة، وانتظر المدة المكتوبة في الرسالة قبل ما تعيد.
• INVALID_URL: المنصة رفضت رابط مو بالصيغة الصحيحة. تتأكد من: رابط الدالة اللي يستدعيه الكود.

أخطاء النشر والتشغيل

• NOT_FOUND: بيانات الدالة أو ملفاتها مو موجودة في المنطقة. تتأكد من: إنك نشرت الدالة، وانتظر دقايق بعد النشر حتى تتحدّث كل المناطق.
• NOT_FOUND_FUNCTION_BLOB: بيانات الدالة موجودة، لكن ملف النشر نفسه مفقود. الرسالة نفس NOT_FOUND، والترويسة فقط تفرّق بينهم. تتأكد من: إن ما فيه نشرين لنفس الدالة في نفس الوقت، وانشرها من جديد بآخر إصدار من Supabase CLI.
• BOOT_ERROR: الدالة ما قدرت تبدأ، مثل خطأ في الكتابة أو import ناقص. تتأكد من: إن الدالة تشتغل عندك بـ supabase functions serve.
• LOAD_FUNCTION_ERROR: المنصة ما قدرت تحمّل بيانات الدالة أو ملفاتها. تتأكد من: إنك تعيد الطلب بعد شوي، وإذا تكرر تواصل مع الدعم.
• LOAD_FUNCTION_METADATA_ERROR: المنصة ما قدرت تجيب بيانات الدالة، ممكن بسبب مشكلة في الـ cache. تتأكد من: إنك تنتظر دقايق وتعيد.
• LOAD_FUNCTION_INVALID_ENTRYPOINT_PATH_ERROR: بيانات الدالة خربانة أو ملف البداية غير صحيح. تتأكد من: إنك تنشر الدالة من جديد.
• LOAD_FUNCTION_UNBUNDLING_ERROR: ملف النشر انجاب لكن ما انفك، وغالبًا لأنه تالف أو ناقص. تتأكد من: إنك تنشر الدالة من جديد.

تبي أحد يتأكد منها؟

إذا عندك رمز واحد وما عرفت سببه، مكالمة استشارية نقرأ فيها الطلب والسجلات ونلقى السبب معك. إذا الأخطاء كثيرة أو في أكثر من مكان، مثل RLS والجلسات مع بعض، فيه الإصلاح المباشر. وإذا منتجك مبني بـ Lovable، شوف مشاكل Lovable و Supabase.