Fetch API: Forward reason from AbortController to fetch Response

at a glance

what changed

Aborting a fetch has two windows. If you abort while the fetch() promise is still pending, the promise rejects with your reason — Chromium already did this (see the earlier abortable-fetch entry). If you abort after the headers arrived — the promise has resolved to a Response, but the body is still streaming — the spec says the reason must also reach everything that is reading that body. That second window is what Chrome 154 fixes:

The normative requirement comes from two places in the Fetch Standard. “Abort a fetch() call” (§5.6):

“To abort a fetch() call with a promise, request, responseObject, and an error: Reject promise with error. … If request’s body is non-null and is readable, then cancel request’s body with error. If responseObject is null, then return. Let response be responseObject’s response. If response’s body is non-null and is readable, then error response’s body with error.”

And HTTP-network fetch (§4.7), for the network-layer teardown of the body stream:

“If aborted, then: If fetchParams is aborted, then: Set response’s aborted flag. If stream is readable, then error stream with the result of deserialize a serialized abort reason given fetchParams’s controller’s serialized abort reason and an implementation-defined realm.”

Note the spec also cancels a readable request body with the same error; the Chrome 154 entry describes the Response-side gap specifically, and the request-body side is not separately called out in the sources read.

syntax

No signatures change. The surfaces whose rejection and error values change are the body members of the Response object, defined by the Body interface mixin (IDL verbatim from the Living Standard, fetched 2026-10-04 — textStream() is a newer spec addition quoted as-is, not part of this Chrome 154 change):

interface mixin Body {
  readonly attribute ReadableStream? body;
  readonly attribute boolean bodyUsed;
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] Promise<Blob> blob();
  [NewObject] Promise<Uint8Array> bytes();
  [NewObject] Promise<FormData> formData();
  [NewObject] Promise<any> json();
  [NewObject] Promise<USVString> text();
  [NewObject] ReadableStream textStream();
};

None of these methods takes arguments; each returns a promise that settles as the body is fully read. The abort reason itself enters the system through AbortController.abort(reason) / AbortSignal, defined in the DOM Standard (IDL verbatim, fetched 2026-10-04):

[Exposed=*]
interface AbortSignal : EventTarget {
  [NewObject] static AbortSignal abort(optional any reason);
  [Exposed=(Window,Worker), NewObject] static AbortSignal timeout([EnforceRange] unsigned long long milliseconds);
  [NewObject] static AbortSignal _any(sequence<AbortSignal> signals);

  readonly attribute boolean aborted;
  readonly attribute any reason;
  undefined throwIfAborted();

  attribute EventHandler onabort;
};

The reason is any JavaScript value. When none is given, the DOM Standard sets the signal’s abort reason “to a new "AbortError" DOMException”, and AbortSignal.timeout() aborts with “a new "TimeoutError" DOMException” — which is what makes timeouts distinguishable from user cancels at the body-read site (see examples). Response objects (and these members) are exposed in Window and Worker contexts.

how the reason travels (and when you still get AbortError)

The reason is not passed around by reference. When a fetch controller is aborted, the Fetch Standard stores a structured-serialized copy, and each consumer deserializes it back into its own realm (abort a fetch controller, quoted verbatim):

“Let fallbackError be an "AbortError" DOMException. Set error to fallbackError if it is not given. Let serializedError be StructuredSerialize(error). If that threw an exception, catch it, and let serializedError be StructuredSerialize(fallbackError). Set controller’s serialized abort reason to serializedError.”

And the reverse step (deserialize a serialized abort reason, quoted verbatim):

“To deserialize a serialized abort reason, given null or a Record abortReason and a realm realm: Let fallbackError be an "AbortError" DOMException. Let deserializedError be fallbackError. If abortReason is non-null, then set deserializedError to StructuredDeserialize(abortReason, realm). If that threw an exception or returned undefined, then set deserializedError to fallbackError. Return deserializedError.”

Practical consequences, all directly from those two algorithms:

• Inputs: any value works as a reason, but only structured-cloneable values survive the trip. Error and DOMException objects, plain objects, strings and numbers arrive intact (as copies).
• Fallback: if the reason cannot be serialized (a function, a value with call-site-only semantics) or deserializes to undefined, consumers on this path receive the generic "AbortError" DOMException instead — the pre-154 behavior, by design.
• Identity: a deserialized reason is a structurally equal copy, not the same object; don’t compare it with === against the value you passed to abort(). (On the same-realm path, §5.6’s abort steps hand the signal’s abort reason to “abort a fetch() call” directly.)
• Lifecycle: the serialized reason is set once, when the controller is aborted; every later delivery — erroring the body stream, rejecting in-flight reader.read() promises, rejecting body-consumption promises — reuses it. A body that was already fully read, or a stream already closed/errored, is not re-errored (“if … is readable” guards every step).

examples

Cancelling a download after the headers arrived, and seeing your reason at the body read:

const controller = new AbortController();

const response = await fetch('/api/export.csv', {
  signal: controller.signal,
});
// Headers are in: the fetch() promise has already resolved.
// The body is still streaming.

// Later, the user clicks "cancel":
controller.abort(new DOMException('User cancelled the export', 'AbortError'));
// ...any value is allowed: controller.abort({ why: 'user-cancel' });

try {
  const text = await response.text();
} catch (err) {
  // Chrome 154+ (and Firefox): err IS the reason passed to abort()
  // (a structured clone of it on the cross-realm path).
  // Chrome <= 153: err was a fresh generic "AbortError" DOMException
  // and the reason was lost.
  console.log(err.message); // "User cancelled the export"
}

Telling a timeout apart from a deliberate cancel while reading response.body — the case that makes this fix useful, because AbortSignal.timeout() aborts with a "TimeoutError" DOMException (DOM Standard, quoted above):

const response = await fetch(url, {
  signal: AbortSignal.any([userController.signal, AbortSignal.timeout(10_000)]),
});

const reader = response.body.getReader();
try {
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    render(value);
  }
} catch (err) {
  // Chrome 154+: the stream is errored with the abort reason.
  if (err instanceof DOMException && err.name === 'TimeoutError') {
    offerRetry();        // the 10 s budget ran out
  } else {
    showCancelled(err);  // the user's own abort reason
  }
}

browser compatibility

BCD has no entry for this behavior change yet: BCD api/Response.json contains no abort-reason subfeature or version note (raw file checked 2026-10-04 — zero matches for “abort”). The table below is therefore interim, built from the ChromeStatus record, the Intent to Ship, and BCD for the prerequisite AbortSignal.reason:

Cross-engine status of the two relevant subtests (“response.arrayBuffer() rejects with abort reason if already aborted”, “Stream errors once aborted with abort reason”) is tracked on wpt.fyi; per-browser subtest results were not individually verified here. Write code that treats the reason as a progressive enhancement: always handle a plain "AbortError" DOMException as the baseline outcome.

security and privacy

No new capability is exposed: the abort reason is a value the page itself supplied to abort(), delivered back to the same page’s own Response object. The structured-serialize/deserialize round trip (quoted in how the reason travels) is the trust boundary: the reason crosses between realms and off the network thread only as a structured clone, never as a live object reference, and anything that cannot be cloned is replaced by the neutral "AbortError" fallback rather than leaked or thrown across the boundary. Nothing about the reason is sent on the network, and the server cannot observe it — aborting still simply tears down the connection (for HTTP/2, the spec transmits an RST_STREAM frame). The change is observable only to script that already holds the Response.

specifications

see also

• MDN: AbortSignal.reason — the reason attribute itself (MDN does not yet document this Chrome 154 body-forwarding change; HEAD-checked 2026-10-04)
• MDN: Response.body and MDN: Using the Fetch API
• chrome-platform-showcase: abort-reason demos (three concepts, all routes 200)
• ChromeStatus — Fetch API: Forward reason from AbortController to fetch Response (5158507786665984)
• blink-dev Intent to Ship · tracking bug 502133195
• ChromeStatus — the original abortable-fetch entry (promise-phase abort)