---
title: "أصلح خطأ Failed to fetch وميّز بين أسبابه الـ3"
description: "TypeError: Failed to fetch يعني أن الطلب لم يحصل على رد HTTP. ترويسة CORS مفقودة، وخادم متوقف، ومضيف غير موجود، كلها تعطي الرسالة نفسها."
canonical: "https://logbrew.co/ar/errors/failed-to-fetch"
last_updated: "2026-11-10"
---

# أصلح خطأ Failed to fetch وميّز بين أسبابه الـ3

`TypeError: Failed to fetch` يعني أن الطلب لم يحصل على رد HTTP. ترويسة CORS مفقودة، وخادم متوقف، ومضيف غير موجود، كلها تعطي الرسالة نفسها.

اختُبر في 10 نوفمبر 2026 باستخدام Chromium 152 و@logbrew/browser 0.1.21 و@logbrew/sdk 0.1.44

بقلم [Furkan Erday](https://github.com/furkanerday). Furkan Erday مؤسس LogBrew، ويبني LogBrew كل يوم باستخدام Claude Code وCodex.

Canonical: https://logbrew.co/ar/errors/failed-to-fetch

## ما الذي يسمّي سبب فشل `fetch()`

| ما الذي حدث | `error.message` | وحدة التحكم |
| --- | --- | --- |
| لا ترويسة `Access-Control-Allow-Origin` | `Failed to fetch` | سياسة CORS |
| لا شيء يستمع على المنفذ | `Failed to fetch` | `ERR_CONNECTION_REFUSED` |
| المضيف بلا سجل DNS | `Failed to fetch` | `ERR_NAME_NOT_RESOLVED` |
| الخادم أجاب بـ500 | لم يُرفض | `500` |

4 طلبات إلى API في مصدر آخر. الكوب الممتلئ يعني أن النص يسمّي السبب.

## اعرف أي سبب لديك

### افتح وحدة تحكم المتصفح

يرفض `fetch()` بالخطأ نفسه `TypeError: Failed to fetch` عند كل فشل في الشبكة. أما سطر وحدة التحكم المجاور فيسمّي السبب الحقيقي.

### أجاب API دون ترويسة CORS

تقول وحدة التحكم `blocked by CORS policy`. أجاب الخادم فعلًا، لكن مصدر الصفحة غير مسموح له بقراءة الرد، فيرمي المتصفح الجواب.

المخرجات

```text
Access to fetch at 'http://127.0.0.1:4874/api/closed' from origin 'http://127.0.0.1:4873' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
```

### لا شيء يستمع على ذلك المضيف والمنفذ

تقول وحدة التحكم `net::ERR_CONNECTION_REFUSED`. API لا يعمل، أو المنفذ في URL خاطئ. شغّله، ثم تحقق من المنفذ.

المخرجات

```text
Failed to load resource: net::ERR_CONNECTION_REFUSED
```

### اسم المضيف لا يُحلّ

تقول وحدة التحكم `net::ERR_NAME_NOT_RESOLVED`. لا يملك DNS سجلًا للمضيف. تحقق من وجود خطأ إملائي في اسم المضيف، ومن متغير البيئة الذي يحمل URL الخاص بـAPI في عملية النشر هذه.

المخرجات

```text
Failed to load resource: net::ERR_NAME_NOT_RESOLVED
```

## أصلحه في كودك

### أرسل ترويسة CORS من API

أجب بالترويسة `Access-Control-Allow-Origin` مضبوطة على مصدر صفحتك، أو على `*` لـAPI عام. في اختبارنا انتقلت نقطة النهاية نفسها من `Failed to fetch` إلى `HTTP 200` بإضافة تلك الترويسة وحدها.

```bash
Access-Control-Allow-Origin: https://app.example.com
```

### تحقق من الحالة، لأن 500 لا يُرفض

يكتمل `fetch()` بنجاح عند أي رد HTTP، بما فيه 404 و500. في اختبارنا وصل رد 500 بالمحتوى `{"error":"tap jammed"}` إلى فرع `then` لا إلى `catch`. اختبر `response.ok` قبل أن تقرأ المحتوى.

```bash
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`);
```

### سجّل URL مع الخطأ

الطلب `fetch()` المرفوض بلا رد، ومكدّسه يشير إلى كودك أنت لا إلى السبب. التقطه حيث تستدعي `fetch()` واحتفظ بالطريقة وURL مع الخطأ، ليعرض لك تتبع الأخطاء أي طلب فشل.

```bash
try {
  return await fetch(url);
} catch (error) {
  console.error("fetch failed", url, error);
  throw error;
}
```

## ما رأيناه في الاختبار

عملت الصفحة على `http://127.0.0.1:4873` في Chromium 152 مع `@logbrew/browser` 0.1.21 وأداة رصد fetch الخاصة به مثبّتة. أجاب API على `http://127.0.0.1:4874` عن 3 مسارات، وأرسلنا 5 طلبات دون `catch`، فوصل كل رفض إلى SDK بوصفه رفضًا غير معالَج.

أجاب `/api/closed` بـ200 دون ترويسة CORS، ورُفض الطلب بالخطأ `TypeError: Failed to fetch`. ورُفض طلب إلى المنفذ 4875، حيث لا يستمع شيء، وطلب آخر إلى `http://keg.invalid/api` بالخطأ نفسه. في الحالات الـ3 كلها كانت `error.message` هي `Failed to fetch`، و`error.name` هو `TypeError`، وأشار المكدّس إلى استدعاء `fetch()` الخاص بنا.

ميّزت وحدة التحكم بينها. قال الأول `blocked by CORS policy`، والثاني `net::ERR_CONNECTION_REFUSED`، والثالث `net::ERR_NAME_NOT_RESOLVED`. أما `/api/broken`، الذي أجاب بـ500 مع الترويسة، فلم يُرفض أصلًا، و`/api/open`، الذي أجاب بـ200 مع الترويسة، أعطى `HTTP 200 {"ok":true}`.

## لماذا يحمل كل سبب الرسالة نفسها

يحوّل معيار Fetch كل فشل قبل الرد إلى 1 شيء، خطأ شبكة، وهو رد من النوع `error` بالحالة 0. وفشل CORS واحد منها. في الوضع `cors`، يعطي المورد الذي لا يفهم بروتوكول CORS خطأ شبكة.

ترفض الدالة `fetch()` الوعد الخاص بها بالخطأ `TypeError` عند خطأ شبكة، ولا شيء غيره. وتقول MDN الأمر نفسه. لا يُرفض الوعد إلا عندما يفشل الطلب، مثلًا عند URL سيئ التكوين أو خطأ شبكة، لا عند حالة HTTP مثل 404 أو 504.

تقول صفحة MDN عن أخطاء CORS إن تفاصيل طلب CORS الفاشل غير متاحة لـJavaScript لأسباب أمنية، وإن وحدة التحكم هي المكان الوحيد الذي تجدها فيه. ويطلب whatwg/fetch#526 أنواع أخطاء أكثر إفادة منذ 2017 وما زال مفتوحًا.

## ما يسجّله LogBrew

وصل كل رفض بوصفه 1 مشكلة باسم `Unhandled promise rejection: TypeError`، مع إطارات مكدّس داخل حزمتنا ومفتاح التجميع `browser.unhandledrejection:TypeError:/app.js`. يخبرك ذلك أين استدعيت `fetch()`، لا ما الذي فشل.

أضافت أداة رصد fetch عنصر Span في التتبّع نفسه، `browser.fetch GET /api/closed`، بالحالة `error` والطريقة ومسار الطلب و`errorType` بقيمة `TypeError`. يسمّي Span الطلب الذي فشل حتى لو لم يسمّه الخطأ.

لم ينتج عن رد 500 أي مشكلة، بل Span فقط بالحالة `error` و`statusCode` بقيمة 500. ونتج عن رد 200 عنصر Span بالحالة `ok`. وهكذا يكون 500 وفشل الشبكة في LogBrew 2 من عناصر Span المختلفة، بينما في كودك لا يصل إلى `catch` إلا الثاني.

## أسئلة شائعة

### ماذا يعني TypeError Failed to fetch؟

لم يستطع المتصفح الحصول على رد HTTP لاستدعاء `fetch()`. كان الخادم غير قابل للوصول، أو لم يُحلّ المضيف، أو حظر CORS الرد. والرسالة واحدة في الحالات الـ3 كلها.

### هل Failed to fetch خطأ CORS دائمًا؟

لا. في اختبارنا أعطت ترويسة CORS المفقودة ومنفذ بلا خادم ومضيف بلا سجل DNS هذه الرسالة كلها. ولا يسمّي السبب إلا سطر وحدة التحكم المجاور.

### لماذا لا يرفض fetch عند 404 أو 500؟

لا يرفض معيار Fetch إلا عند خطأ شبكة. أي رد HTTP بأي حالة هو رد، لذلك يكتمل `fetch()` بنجاح وتختبر `response.ok` بنفسك.

### كيف ألتقط Failed to fetch في JavaScript؟

غلّف الاستدعاء بـ`try` و`catch`، أو أضف `.catch()` إلى الوعد. الخطأ هو `TypeError` بلا رد، لذلك سجّل URL والطريقة بنفسك.

### هل يعني Failed to fetch أن الخادم متوقف؟

أحيانًا. يعطي الخادم المتوقف `net::ERR_CONNECTION_REFUSED` في وحدة التحكم. ويأتي `Failed to fetch` نفسه أيضًا من ترويسة CORS مفقودة أو اسم مضيف بلا سجل DNS.

## اعرف أي طلب فشل، ولماذا

يسجّل SDK المتصفح من LogBrew كل `fetch()` بوصفه Span بطريقته ومساره وحالته، في التتبّع نفسه مع الخطأ الذي أثاره. ابدأ بخطة مجانية سخية دون بطاقة.

[ابدأ مجانًا](https://logbrew.co/ar)

## المصادر

- [MDN, Window: fetch() method](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch)
- [MDN, CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS/Errors)
- [Fetch Standard, The fetch() method](https://fetch.spec.whatwg.org/#fetch-method)
- [whatwg/fetch#526](https://github.com/whatwg/fetch/issues/526)

## المزيد من حلول أخطاء JavaScript

- [أصلح خطأ Script error الذي يخفي رسالته وملفه وسطره](https://logbrew.co/ar/errors/script-error)
- [أخطاء JavaScript أعدنا إنتاجها، وكيف تصلح كلًا منها](https://logbrew.co/ar/errors)