throw()sends an error into a paused generator. The error appears exactly where the generator is waiting, at the yield, as if that yield had thrown it.
If the generator has a try...catch around that yield, it can handle the problem and carry on. If it does not, the generator ends and the error travels out to the code that called throw().
Remember
generator.throw(error);
error → thrown at the paused yield
caught inside → generator goes on, and the result
is { value, done: false } or done: true
not caught → generator finishes, error comes out
of throw() to the caller
Syntax
Call throw() on a generator object with the error you want to send. Use an Error object, as with a normal throw.
JavaScript
generator.throw(error);
generator.throw(new Error("Something went wrong"));
Call
What it does
gen.throw(new Error("Stop"))
Throw an error at the paused yield.
try { gen.throw(err); } catch (e) { ... }
Catch the error outside when the generator does not catch it.
const r = gen.throw(err);
When the generator catches the error and yields again, r is { value, done: false }.
Built into JavaScript (ES2015). Every generator object has it; no import required. Siblings: next() and return().
Library declarations
JavaScript
// Generator.prototype.throw (ES2015)
generator.throw(exception)
// returns { value: any, done: boolean }
// or throws the error again if the generator does not catch it
Parameters
Parameter
Description
exception
The error to throw inside the generator. It is best to pass an Error object, because it carries a message and a stack. Any other value, such as a string, also works.
Return Value
Return Value
Description
{ value, done: false }
The generator caught the error and paused at another yield. value is what that yield produced.
{ value, done: true }
The generator caught the error and then finished. value is its return value, or undefined.
The error itself (thrown)
The generator did not catch the error. It is finished, and the error is thrown again from throw().
JavaScript Examples
Example 1 — Throw an Error the Generator Does Not Catch
The generator has no try...catch, so the error ends it and comes out of throw().
step 1
Caught outside: Stop now
value: undefined, done: true
How It Works
Pause at a yield. The first next() gives "step 1" and the generator waits at that yield.
The error appears there.gen.throw(...) makes the yield throw. The generator has no catch, so it ends, and the error comes out of throw() into your own catch block.
The generator is finished."step 2" is never produced. The next next() says done: true.
Example 2 — Catch the Error Inside the Generator
This time the generator has a try...catch around its yield and recovers.
value: working, done: false
value: recovering from disk full, done: false
value: finished, done: true
How It Works
Working. The first next() pauses inside the try block at yield "working".
The error is handled inside.gen.throw(...) throws at that yield, the catch block receives it, and the generator yields a recovery message. Because it yielded again, the result is done: false and nothing is thrown outside.
Finish normally. The next next() runs past the catch block to return "finished", so done is true.
Example 3 — Throw into a Generator That Has Not Started
See what happens when throw() arrives before the first next(), and when you throw a plain string.
RangeError: too early
value: undefined, done: true
Caught: plain text
true
How It Works
No yield to throw at.fresh has not run yet, so it is not paused anywhere. throw() ends it immediately and the RangeError comes out of the call.
Already finished. The following next() shows done: true, because the error ended the generator.
Any value works. The second generator is paused after next(). Throwing the string "plain text" still ends it, and the string arrives in the catch block. Prefer Error objects in real code.
Compatibility
Browser & Runtime Support
Generators arrived with ES2015. Every current browser and Node.js version supports them, including throw().
✓ ES2015 · Widely supported
generator.throw()
Supported in Chrome 39+, Edge 13+, Firefox 26+, Safari 10+ and current Node.js, Deno and Bun. Internet Explorer never got generators.
ES2015Standard since
Google Chrome39+ · Desktop & Mobile
Full support
Microsoft Edge13+ · Legacy & Chromium
Full support
Mozilla Firefox26+ · Desktop & Mobile
Full support
Apple Safari10+ · macOS & iOS
Full support
Opera26+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebViewRecent versions · Chromium based
Supported
Node.jsAll current versions · Server runtime
Supported
DenoAll versions · JavaScript runtime
Supported
BunAll versions · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
generator.throw()Excellent
Bottom line: Safe to use in every current browser and in Node.js. Only Internet Explorer lacks function*, and it is no longer supported.
Frequently Asked Questions
It throws an error inside a paused generator, at the yield where the generator is waiting. If the generator catches the error with try...catch it can continue; if not, the generator ends and the error comes out of the throw() call.
The same kind of result as next(): an object { value, done }. If the generator yields again after catching, you get done: false and the new value. If it finishes, you get done: true and its return value.
It ends for good. The error is thrown out of the throw() call, and every later next() returns { value: undefined, done: true }. You need a new generator object to start again.
The throw statement is written in your code and throws where it stands. The throw() method belongs to the generator object and makes the generator throw at its paused yield, so the generator can react with its own try...catch.
When the code that consumes values wants to tell the generator that something went wrong, for example that a download failed or the user cancelled. The generator can catch the error, clean up or choose a fallback value, and go on.