network.fetchError event

The network.fetchError event of the network module fires when a request ends in an error, for example because the host can't be reached or the request is aborted.

Event data

The params field in the event notification is an object with the following fields:

context

A string that contains the ID of the context in which the request was made, or null if the request wasn't made by a document in a context, for example a request made by a worker.

errorText

A string that describes the error, such as NS_ERROR_UNKNOWN_HOST or net::ERR_NAME_NOT_RESOLVED for a host name that can't be resolved. The text is browser-specific, so don't rely on this value for assertions in tests.

isBlocked

A boolean that indicates whether the request is blocked by an intercept. It is always false for this event because no intercept phase applies to it, so the event never includes the intercepts field.

A string that contains the UUID that uniquely identifies the navigation that the request is part of, or null if the request isn't a navigation request. For example, the value is null when requesting a document's subresources, such as stylesheets and scripts, or when making a request with fetch().

For a failed navigation, this field contains the navigation ID reported by the browsingContext.navigationStarted event.

If the navigation was started with browsingContext.navigate, the command can return an error instead of a navigation ID.

Other events related to this navigation share the same navigation ID, including events in the browsingContext and network modules.

redirectCount

A non-negative integer that contains the number of redirects the browser has followed for this request. It is 0 for the original request and increases by one with each redirect.

request

An object that describes the request. It contains the following fields:

bodySize

A non-negative integer that contains the size of the request body in bytes, or null if the request has no body.

cookies

An array of objects, each representing a cookie sent with the request. The array is empty if the request has no Cookie header. Each object contains the following fields and may additionally include browser-specific fields:

domain

A string that contains the domain of the cookie.

expiry Optional

A non-negative integer that contains the expiry time of the cookie, as seconds elapsed since the epoch. This field is omitted for a cookie that has no expiry time, such as a session cookie.

httpOnly

A boolean that indicates whether the cookie is hidden from page scripts by its HttpOnly attribute (true) or is accessible to them (false).

name

A string that contains the name of the cookie.

path

A string that contains the path of the cookie.

sameSite

A string that indicates the cookie's SameSite setting. It has one of the following values:

  • default: The cookie has no SameSite attribute or has an unrecognized value, so the browser's default behavior applies.
  • lax: The cookie has SameSite=Lax.
  • none: The cookie has SameSite=None.
  • strict: The cookie has SameSite=Strict.
secure

A boolean that indicates whether the cookie is restricted to secure connections by its Secure attribute (true) or can be sent over insecure connections (false).

size

A non-negative integer that contains the combined size of the cookie's name and value, in bytes.

value

An object that contains the value of the cookie. It contains the following fields:

type

A string that indicates how the cookie value is encoded. It has one of the following values:

  • base64: The value is Base64-encoded bytes because the bytes are not valid UTF-8.
  • string: The value is text decoded from UTF-8 bytes.
value

A string that contains the cookie value in the encoding specified by the type field.

destination

A string that contains the destination of the request, such as document, script, or style. The string is empty for requests made with fetch() or XMLHttpRequest.

headers

An array of objects, each representing a header of the request, including headers added with the network.setExtraHeaders command. Each object contains the following fields:

name

A string that contains the header name, such as Accept.

value

An object that contains the header value. It contains the following fields:

type

A string that indicates how the header value is encoded. It has one of the following values:

  • base64: The value is Base64-encoded bytes because the bytes are not valid UTF-8.
  • string: The value is text decoded from UTF-8 bytes.
value

A string that contains the header value in the encoding specified by the type field.

headersSize

A non-negative integer that contains the size of the request headers in bytes. For protocols that compress headers, such as HTTP/2, it represents the compressed size.

initiatorType

A string that indicates what started the request, such as fetch, link, or script. For a request with no initiator type, such as the request for a page loaded into a tab, the value is null instead of a string. See PerformanceResourceTiming.initiatorType for descriptions of common values.

method

A string that contains the HTTP request method, such as GET or POST.

request

A string that contains the ID of the request. The ID stays the same even when the request is redirected.

timings

An object that contains the times at which the stages of the request happened. The timeOrigin field contains a time in milliseconds since the epoch. The other fields in this object contain times in milliseconds relative to timeOrigin. A field is 0 if its stage hasn't happened, for example the redirect fields for a request that wasn't redirected. All the fields are 0 if the request wasn't made by a document or a worker. It contains the following fields:

connectEnd

A number that represents the time when the browser finished establishing the connection to the server, similar to PerformanceResourceTiming.connectEnd.

connectStart

A number that represents the time when the browser started establishing the connection to the server, similar to PerformanceResourceTiming.connectStart.

dnsEnd

A number that represents the time when the browser finished the domain name lookup, similar to PerformanceResourceTiming.domainLookupEnd.

dnsStart

A number that represents the time when the browser started the domain name lookup, similar to PerformanceResourceTiming.domainLookupStart.

fetchStart

A number that represents the time when the browser started fetching the resource after any redirects, similar to PerformanceResourceTiming.fetchStart.

redirectEnd

A number that represents the time when the browser received the last byte of the response to the last redirect, similar to PerformanceResourceTiming.redirectEnd.

redirectStart

A number that represents the time when the request that was redirected first started, similar to PerformanceResourceTiming.redirectStart.

requestStart

A number that represents the time when the browser started sending the request, similar to PerformanceResourceTiming.requestStart.

requestTime

A number that represents the time when the request started, similar to PerformanceEntry.startTime.

responseEnd

A number that represents the time when the browser received the last byte of the response, similar to PerformanceResourceTiming.responseEnd.

responseStart

A number that represents the time when the browser received the first byte of the response, similar to PerformanceResourceTiming.responseStart.

timeOrigin

A number that represents the time origin of the document or worker that made the request.

tlsStart

A number that represents the time when the browser started the TLS handshake to secure the connection, similar to PerformanceResourceTiming.secureConnectionStart.

url

A string that contains the URL of the request.

timestamp

A non-negative integer that represents the time when the event was fired, as milliseconds elapsed since the epoch.

userContext Optional

A string that contains the ID of the user context in which the request was made, or null if the request wasn't made by a document in a context.

Description

In the lifecycle of a request, this is the last event for a request that fails. It can fire at any point after network.beforeRequestSent, for example:

  • Before a response arrives, when the browser can't resolve the host name or the server refuses the connection
  • After network.responseStarted, when the page aborts the request while the browser is still receiving the response body, for example with an AbortSignal

If the client is subscribed to both events, it receives network.beforeRequestSent before network.fetchError, even for a request that fails before it is sent. This event has no response field even if network.responseStarted fired for the request.

When a navigation fails, you can use this event's navigation ID to match the event with the corresponding browsingContext.navigationStarted event.

Examples

Receiving an event when a host can't be reached

Assume you have a WebDriver BiDi connection, an active session, and a subscription to network.fetchError.

Suppose a tab has loaded https://example.com/. The page calls fetch("https://unknown.invalid/items"). The .invalid domain never resolves, so the request fails. The browser sends the following event (for brevity, the headers array has been shortened and some fields in the request object have been omitted):

json
{
  "type": "event",
  "method": "network.fetchError",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "errorText": "NS_ERROR_UNKNOWN_HOST",
    "isBlocked": false,
    "navigation": null,
    "redirectCount": 0,
    "request": {
      "cookies": [],
      "destination": "",
      "headers": [
        {
          "name": "Host",
          "value": {
            "type": "string",
            "value": "unknown.invalid"
          }
        },
        {
          "name": "Accept",
          "value": {
            "type": "string",
            "value": "*/*"
          }
        },
        {
          "name": "Origin",
          "value": {
            "type": "string",
            "value": "https://example.com"
          }
        }
      ],
      "headersSize": 326,
      "initiatorType": "fetch",
      "method": "GET",
      "request": "b9e201af-6475-4bea-a174-51a8290f8087",
      "url": "https://unknown.invalid/items"
    },
    "timestamp": 1791903586722,
    "userContext": "default"
  }
}

The errorText describes the failed domain name lookup. In the page, the fetch() call rejects with a TypeError.

Receiving an event when a navigation fails

Using the same connection, session, and subscription as in the first example, assume you also have a subscription to browsingContext.navigationStarted.

Suppose you use browsingContext.navigate to load https://example.com:59999/, a port where no server is listening.

The browser sends a browsingContext.navigationStarted event with the navigation ID:

json
{
  "type": "event",
  "method": "browsingContext.navigationStarted",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "timestamp": 1791903594250,
    "url": "https://example.com:59999/",
    "userContext": "default"
  }
}

When the server refuses the connection, the browser sends the following network.fetchError event with the same navigation ID (only some of the fields are shown):

json
{
  "type": "event",
  "method": "network.fetchError",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "errorText": "NS_ERROR_CONNECTION_REFUSED",
    "isBlocked": false,
    "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "redirectCount": 0,
    "request": {
      "destination": "document",
      "method": "GET",
      "request": "37cf22b4-f399-4450-828d-d54fce56004e",
      "url": "https://example.com:59999/"
    },
    "timestamp": 1791903594254
  }
}

The browsingContext.navigate command returns an unknown error with no navigation ID. To match this event to the navigation, use the navigation ID from the browsingContext.navigationStarted event.

Specifications

Specification
WebDriver BiDi
# event-network-fetchError

Browser compatibility

See also