JavaScript AsyncGenerator throw() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
AsyncGenerator

Definition

asyncGenerator.throw(error) resumes a paused async generator by throwing error at the yield where it stopped, and returns a Promise like next().

If the generator catches the error with a try...catch around that yield, it keeps running and the promise resolves to the next { value, done }. If not, finally blocks run, the generator is finished, and the promise rejects with the same error. Use it to tell a producer that something went wrong, so it can skip an item or retry.

Remember
await gen.throw(new Error("oops"))

caught inside (try/catch around yield)
  → generator keeps running
  → resolves with the next { value, done }

not caught inside
  → finally blocks run, generator is finished
  → the promise rejects with the error

before the first next() → rejects, body never runs

Syntax

Call throw() on a generator that is paused at a yield. Wrap the call in try...catch in case the generator does not handle the error.

JavaScript
const gen = myAsyncGenerator();

await gen.next();
const result = await gen.throw(new Error("message"));
CallWhat it does
asyncGenerator.throw(error)Throw at the paused yield; get a Promise of the next { value, done }.
asyncGenerator.throw(new Error("text"))Recommended: an Error carries a message and a stack.
await gen.throw(err) in try...catchHandle the rejection if the generator does not catch it.

Built into JavaScript (ES2018); no import required. Siblings: next() and return().

Library declarations
JavaScript
// AsyncGenerator.prototype.throw (ES2018)
asyncGenerator.throw(exception)

// returns Promise<{ value: any, done: boolean }>
// rejects when the generator does not catch it

Parameters

ParameterDescription
exceptionRequired in practice. The value to throw inside the generator; an Error such as new Error("timeout") is the clearest choice.

Return Value

Return ValueDescription
Promise of { value, done: false }The generator caught the error and reached another yield.
Promise of { value, done: true }The generator caught the error and then finished.
Rejected promiseNot caught inside, or not started yet: rejects with the error and the generator is finished.

JavaScript Examples

Example 1 — An Uncaught Error Finishes the Generator

The generator has no catch, so the error comes straight back to the caller after the finally cleanup.

JavaScript
async function* downloads() {
  try {
    yield "file-1.txt";
    yield "file-2.txt";
    yield "file-3.txt";
  } finally {
    console.log("cleanup: download list closed");
  }
}

async function run() {
  const files = downloads();
  console.log("got " + (await files.next()).value);

  try {
    await files.throw(new Error("network lost"));
  } catch (err) {
    console.log("caught outside: " + err.message);
  }

  const after = await files.next();
  console.log("after throw: done = " + after.done);
}

run();
Try It Yourself

How It Works

  1. Error lands at the yield. The generator is paused at yield "file-1.txt", so that line now behaves like throw new Error("network lost").
  2. No catch, only finally. The cleanup message prints first; then the promise from throw() rejects and the caller's catch reads err.message.
  3. No more files. The generator is finished, so the following next() reports done = true and file 2 and 3 are never produced.

Example 2 — Catch the Error Inside and Retry

A try...catch around yield lets an upload job survive a timeout and try again.

JavaScript
async function* uploader(file) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      yield "uploading " + file + " (attempt " + attempt + ")";
      return "uploaded " + file;
    } catch (err) {
      console.log("problem: " + err.message);
    }
  }
  return "gave up on " + file;
}

async function run() {
  const job = uploader("photo.png");
  let step = await job.next();
  console.log(step.value);

  step = await job.throw(new Error("timeout"));
  console.log(step.value);

  step = await job.next();
  console.log(step.value + " | done: " + step.done);
}

run();
Try It Yourself

How It Works

  1. Report a failure. job.throw(new Error("timeout")) raises the error at the paused yield inside the try block.
  2. Recover inside. The generator's catch prints the problem, the for loop moves on to attempt 2, and the promise resolves with that new yielded value instead of rejecting.
  3. Finish normally. The next plain next() continues after the yield, reaches return, and resolves to done: true with the success text.

Example 3 — throw() Before the First next()

A generator that has not started cannot catch anything: the promise rejects and the generator is closed.

JavaScript
async function* guarded() {
  try {
    console.log("body started");
    yield "ready";
  } catch (err) {
    console.log("inner catch: " + err.message);
  }
}

async function run() {
  const gen = guarded();
  try {
    await gen.throw(new Error("cancelled before start"));
  } catch (err) {
    console.log("rejected: " + err.message);
  }

  const after = await gen.next();
  console.log("value: " + after.value + ", done: " + after.done);
}

run();
Try It Yourself

How It Works

  1. Not paused anywhere. guarded() has not run a single line, so there is no yield inside the try to throw at.
  2. Straight rejection. The error skips the body completely: neither "body started" nor "inner catch" is printed, and the outer catch receives it.
  3. Closed afterwards. Like an uncaught error, this finishes the generator, so the following next() resolves to value: undefined, done: true.

Browser & Runtime Support

AsyncGenerator.prototype.throw() shipped with async iteration in ES2018 and behaves the same in browsers and server runtimes.

✓ Baseline · ES2018

AsyncGenerator.prototype.throw()

Supported in Chrome 63+, Firefox 55+, Safari 12+, Edge 79+, and Node.js 10+. Not available in Internet Explorer.

96% Modern browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
AsyncGenerator throw() Excellent

Bottom line: Safe in every current browser and Node.js LTS release. One runtime difference: an unhandled rejection stops a Node.js 15+ process by default, while browsers only log "Uncaught (in promise)".

Frequently Asked Questions

It resumes a paused async generator by throwing the given value at the yield where it stopped, and returns a Promise. The generator can catch the error and continue, or let it escape, and then the promise rejects.
Its catch block runs and execution continues from there. The promise from throw() resolves with the next { value, done }: the next yielded value, or done: true if the generator then finishes.
Any finally blocks around the yield run, the generator is finished, and the promise rejects with the same error. Later next() calls resolve to { value: undefined, done: true }.
Yes, but the generator cannot catch it because it is not paused inside a try block. The promise rejects right away, the body never runs, and the generator is closed.
When the consumer must tell the producer that something went wrong: a value failed validation, an upload timed out, or the user cancelled a step. The generator can catch it and skip, retry, or log. for await...of only uses next() and return(), never throw().

Back to the Method Index

You have covered next(), return() and throw(). Review all AsyncGenerator methods and related syntax in one place.

Method Index →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful