Syntax

cancel()
cancel(reason)

Parameters

reason Optional: A human-readable reason for the cancellation. This is passed to the underlying source, which may or may not use it.

Return value

A Promise, which fulfills with undefined value.

Exceptions

TypeError: The stream you are trying to cancel is not a ReadableStream, or it is locked.

In the following example, a stream is used to fetch the WHATWG HTML spec chunk by chunk; each chunk is searched for the string "service workers". When the search terms is found, cancel() is used to cancel the stream — the job is finished so it is no longer needed.

html

<pre id="output"></pre>

const output = document.getElementById("output");
function log(text) {
  output.textContent += `${text}\n`;
}

const searchTerm = "service workers";
// Chars to show either side of the result in the match
const contextBefore = 30;
const contextAfter = 30;
const caseInsensitive = true;
const url = "https://html.spec.whatwg.org/";
log(`Searching '${url}' for '${searchTerm}'`);
fetch(url)
  .then((response) => {
    log("Received headers");
    const decoder = new TextDecoder();
    const reader = response.body.getReader();
    const toMatch = caseInsensitive ? searchTerm.toLowerCase() : searchTerm;
    const bufferSize = Math.max(toMatch.length - 1, contextBefore);
    let bytesReceived = 0;
    let buffer = "";
    let matchFoundAt = -1;
    return reader.read().then(function process(result) {
      if (result.done) {
        log("Failed to find match");
        return;
      }
      bytesReceived += result.value.length;
      log(`Received ${bytesReceived} bytes of data so far`);
      buffer += decoder.decode(result.value, { stream: true });
      // already found match & just context-gathering?
      if (matchFoundAt === -1) {
        matchFoundAt = (
          caseInsensitive ? buffer.toLowerCase() : buffer
        ).indexOf(toMatch);
      }
      if (matchFoundAt === -1) {
        buffer = buffer.slice(-bufferSize);
      } else if (
        buffer.slice(matchFoundAt + toMatch.length).length >= contextAfter
      ) {
        log("Here's the match:");
        log(
          buffer.slice(
            Math.max(0, matchFoundAt - contextBefore),
            matchFoundAt + toMatch.length + contextAfter,
          ),
        );
        log("Cancelling fetch");
        reader.cancel();
        return;
      } else {
        log("Found match, but need more context…");
      }
      // keep reading
      return reader.read().then(process);
    });
  })
  .catch((err) => {
    log(
      "Something went wrong. See devtools for details. Does the response lack CORS headers?",
    );
    throw err;
  });

Specifications

Specification
Streams # ref-for-rs-cancel③

Browser compatibility

Help improve MDN

Yes No

Learn how to contribute

This page was last modified on Jun 13, 2025 by MDN contributors.