Skip to content

[JSC] An Exception remembers the async context it was thrown in - #689

Merged
dylan-conway merged 2 commits into
mainfrom
claude/exception-carries-async-context
Sep 17, 2026
Merged

dylan-conway merged 2 commits into
mainfrom
claude/exception-carries-async-context

Conversation

@dylan-conway

Copy link
Copy Markdown
Member

What

VM::throwException notes the current async context (JSGlobalObject::m_asyncContextData field 0) on the JSC::Exception the first time it is thrown. Exception::asyncContext() returns it; it is empty for an Exception that was never thrown, or thrown before the embedder started tracking async contexts.

Rethrowing the same Exception keeps the context of the first throw.

Why

An embedder reports an exception nobody caught after whoever entered the async context to call the script has left it:

  • a native caller that entered a callback's captured context restores it when the call returns, and reports afterwards;
  • the queueMicrotask job restores the context before it reports;
  • script that ran the callback inside AsyncLocalStorage.run() / AsyncResource.runInAsyncScope() has unwound out of it by the time the exception reaches native code.

In all three the global object's async context no longer says where the error happened. The exception itself is the one thing that reaches every reporter, so it carries the answer.

Also

#685 handed the context to Bun__reportUnhandledError as a third argument from the queueMicrotask job only. That is no longer needed: the job's reporting goes back to how it was, and the hook takes two arguments again.

Cost

Nothing when no exception is thrown. On a throw: one branch on isAsyncContextTrackingEnabled(), and with tracking on, two loads and one barriered store, next to the stack-trace capture Exception::create already does. Exception gains one WriteBarrier<Unknown>.

An embedder reports an exception nobody caught after whoever entered the
async context to call the script has left it: a native caller restores the
context when the call returns, the queueMicrotask job restores it before it
reports, and script that ran the callback inside AsyncLocalStorage.run() has
unwound out of it. By then the global object's async context no longer says
where the error happened.

VM::throwException now notes the current async context on the Exception the
first time it is thrown (only once the embedder has started tracking async
contexts). Rethrowing the same Exception keeps the context of the first
throw. Exception::asyncContext() is empty for an Exception that was never
thrown.

With that, the queueMicrotask job no longer needs to hand the context to
Bun__reportUnhandledError separately, so the hook goes back to two arguments.
@dylan-conway
dylan-conway merged commit 000c489 into main Sep 17, 2026
46 checks passed
@coderabbitai

coderabbitai Bot commented Sep 17, 2026

Copy link
Copy Markdown

Review Change StackReview Change Stack


Comment @coderabbitai help to get the list of available commands.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Beyond the inline finding, I also checked: the unconditional #include "AsyncContextSwapScope.h" in VM.cpp is safe without USE(BUN_JSC_ADDITIONS) (the header's body is guarded); the new WriteBarrier<Unknown> is visited in Exception::visitChildrenImpl; and the termination-exception early returns in VM::throwException leave the field empty as the header comment says.

Extended reasoning...

A verified inline finding about a second JSGlobalObject's async-context slot (node:vm contexts) is being posted, so approval is not on the table. The remaining candidates were checked against the code: the header is wrapped in #if USE(BUN_JSC_ADDITIONS), the barrier is appended in visitChildrenImpl, and the set happens after the termination-exception early returns, matching the documented empty cases. The Bun__reportUnhandledError two-argument signature is an ABI contract with oven-sh/bun and must land alongside the matching Bun change; that is outside this repository.

Comment on lines +1320 to +1321
if (isAsyncContextTrackingEnabled() && !exceptionToThrow->asyncContext())
exceptionToThrow->setAsyncContext(*this, AsyncContextSwapScope::current(*this, globalObject));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Unhandled errors thrown by code of a second global object (a node:vm context) are reported with no AsyncLocalStorage store after merging, where the base reported the job's store. VM.cpp:1321 reads the slot of the globalObject handed to throwException, which for a JS throw is the throwing code's lexical global (LLIntSlowPaths.cpp:2437), not the global whose slot the job entered. That global's slot is undefined, and undefined is non-empty, so the rethrow on the main global never overwrites it. Fix: record the context of the global whose slot the job installed (a VM-level slot, or the entered global), or leave the field empty when the throwing global's slot was never entered so the reporter can fall back.

Extended reasoning...

Every JSGlobalObject gets its own m_asyncContextData tuple in init (JSGlobalObject.cpp:2240). AsyncContextSwapScope::enter installs the captured context only on the job's globalObject (AsyncContextSwapScope.h:152). The trigger needs Bun's node:vm contexts, which are separate JSGlobalObjects in the same VM. Script: als.run(store, () => queueMicrotask(() => vm.runInNewContext('throw new Error("x")'))). The microtask runs on the main global with store installed in the main global's slot. The vm-context code executes op_throw; LLINT_THROW at LLIntSlowPaths.cpp:2437 calls throwException with the code block's global, the vm context global. VM.cpp:1320 sees asyncContext() empty and VM.cpp:1321 stores current(vm, vmGlobal), which is that global's field 0: undefined. Bun's runInNewContext rethrows on the main global; VM.cpp:1320 now sees a non-empty undefined and keeps it. runInternalMicrotask restores and calls Bun__reportUnhandledError (JSMicrotask.cpp:2198); the embedder reads exception->asyncContext() and gets undefined. On the base, JSMicrotask.cpp read AsyncContextSwapScope::current(vm,…

Verification: normal (narrow: needs node:vm contexts + AsyncLocalStorage + an uncaught throw inside a queueMicrotask job), when script scheduled under an ALS store runs code of a second JSGlobalObject in the same VM that throws and nothing catches it. Mechanism verified in this checkout: (1) the async-context slot is per global object — Source/JavaScriptCore/runtime/JSGlobalObject.cpp:2237-2240 inside…

@github-actions

Copy link
Copy Markdown

Preview build of a3bd90e: autobuild-preview-pr-689-a3bd90e7

dylan-conway added a commit to oven-sh/bun that referenced this pull request Sep 17, 2026
… thrown

Native code that calls a graph's handler has left that handler's async
context by the time it reports what the handler threw, so reading the
current context at report time sent the errors of socket, websocket, UDP,
fs.watch, zlib, http2 and node:http listeners to the host.

The engine now notes on a JSC::Exception the async context it was first
thrown in (oven-sh/WebKit#689; WebKit updated to 000c48997255), and
attribution reads that. The context argument that was threaded from the
queueMicrotask job through Bun__reportUnhandledError is gone again.

A value nobody threw (a socket error with no `error` handler), and a thrown
value a dispatcher has already unwrapped, is reported from inside the context
of the script that owns the thing: Bun.listen/Bun.connect handlers, UDP
sockets, Bun.serve's websocket handlers and the node:http request path now
enter it for the whole dispatch, as Bun.serve's fetch path already did.

Also:
- node:http's server socket stores ondata/ondrain/onclose with the async
  context of whoever set them, so a `req.socket` listener runs in the
  context of the script that added it.
- The scope that runs onError and the process's handlers makes its owner's
  context current in both halves (the async context and the context native
  code entered), so a handler called from inside a stopped graph's dispatch
  is not called for nobody.
- process.nextTick's loop no longer catches in JS. What a tick throws reaches
  JSNextTickQueue::drain as it was thrown; drain reports it and resumes the
  queue. A throw out of run() inside a host tick is now the graph's, as it is
  from a timer.
Jarred-Sumner added a commit to oven-sh/bun that referenced this pull request Sep 17, 2026
Bumps `WEBKIT_VERSION` from `c28156899e5f` to `000c48997255` (current
oven-sh/WebKit `main`). The
`autobuild-000c48997255272cd7e3ae7047e87b955b38989b` release exists.

oven-sh/WebKit changes picked up:

- [JSC] Count an adopted typed array vector once, and stop counting the
ArrayBuffers an eden collection freed (oven-sh/WebKit#684)
- [JSC] Run a CommonJS module's generator before its importing graph
links, not when its fetch completes (oven-sh/WebKit#662)
- SourceCodeKey: restore source string comparison in operator==
(oven-sh/WebKit#346)
- [JSC] Hand Bun__reportUnhandledError the async context the failed
queueMicrotask job ran in (oven-sh/WebKit#685)
- [JSC] AbstractModuleRecord::link: one throw scope for the whole
function (oven-sh/WebKit#688)
- [JSC] An Exception remembers the async context it was thrown in
(oven-sh/WebKit#689)

Not built or tested locally; relying on CI.
dylan-conway added a commit to oven-sh/bun that referenced this pull request Sep 17, 2026
…mmonJS (#42590)

### What does this PR do?

Finishes `Bun.ModuleGraph` (experimental): many instances of one app in
one process, with one copy of its compiled code.

```ts
const graph = new Bun.ModuleGraph({ globals: { process: tenantProcess }, onError });
const app = await graph.import("./app.ts");
await graph.run(() => app.handle(request));
graph.dispose();
```

The whole API: `new Bun.ModuleGraph({ globals?, onError? })`,
`graph.import(specifier)`, `graph.run(fn, ...args)`, `graph.dispose()`
(also `Symbol.dispose`), and the static `Bun.ModuleGraph.current`.
Documented in `docs/runtime/module-graph.mdx`; typed in
`packages/bun-types/bun.d.ts`.

- **Every graph has a context of its own for timers and I/O.** What its
code opens is the graph's: timers, `Bun.serve` / `Bun.listen` servers,
sockets, `fetch`, WebSockets, watchers, child processes (including
`Bun.$`), workers, database connections, files opened through
`Bun.file().writer()`, `bun:sqlite` and `node:sqlite`, and graphs its
code makes. The context follows the code the way `AsyncLocalStorage`
does: through `await`, timers, socket handlers and event listeners.
- **`graph.dispose()` behaves like `worker.terminate()`.** Everything
the graph opened is closed and what it had in flight is discarded:
nothing of the graph is called from the event loop again and its pending
promises stay pending. No `close` / `onExit` / `'error'` callbacks, no
rejections. From then on `graph.import()`, `graph.run()` and the graph's
`require()` fail with `ERR_INVALID_STATE`.
- **What a disposed graph's leftover code starts does not start.**
Microtasks and `process.nextTick` callbacks the graph had already queued
still run once (the engine's promise machinery is not changed). What
they ask for does not leave the process: a connection is not dialed, a
UDP socket is not bound, nobody can connect to a server it listens with,
and the promise stays pending instead of rejecting, so code that retries
on failure stops there. The exception is a child process, which is
started and then killed.
- **`graph.run(fn, ...args)`** calls `fn` inside the graph's context. A
function runs in its caller's context, whichever graph defined it, so
code of a graph that the host calls directly runs as the host.
`Bun.ModuleGraph.current` is the graph whose context the caller is in.
- **The first module a graph `import()`s is its main module**:
`import.meta.main` and `require.main === module` are true in it and in
no other module of the graph.
- **CommonJS is per graph**: a graph has its own `require.cache`, and
`require()`, `createRequire()` and `new Module()` belong to the context
they are called in.
- **Errors belong to the context they happen in.** An uncaught exception
goes to the `onError` of the graph in whose context it was *thrown*,
whoever wrote the code and whatever it unwound through afterwards; that
includes a synchronous throw that escapes `graph.run(fn)` when the
caller does not catch it (`run()` still rethrows to its caller). An
unhandled rejection goes to the graph in whose context the promise was
rejected. An error no code threw (a socket of the graph's failing with
no `error` handler) goes to the graph that opened the thing. `onError`
runs in the context the graph was made in, so what it throws, rejects or
starts is its maker's, and what escapes it goes on to the maker and does
not come back to the same handler. A graph with no `onError` hands its
errors to its maker's. An unhandled `graph.import()` promise is its
caller's.
- **Shared, and therefore not the graph's**: `globalThis`, `process`
(unless replaced through `globals`), plugins, native addons,
`http.globalAgent` / `https.globalAgent` (a request with no `agent` uses
a connection that is not the graph's; code whose connections should go
with its graph passes an `Agent` it made), listeners a graph puts on
something the host owns, and file descriptors that script holds (one
from `fs.openSync()`, or inside a `FileHandle` or an fs stream): those
are the script's to close before `dispose()`. `node:quic` endpoints are
not covered yet. It is not a security sandbox.

How it is built:

1. **Contexts.** A Rust `ScriptExecutionContext` holds an intrusive list
of `AbortHandle`s (membership in the context, plus optionally the
`AbortSignal` script passed). It replaces the `ActiveHandle` registry: a
server, socket, watcher, fetch, child, upload, cron job and so on embeds
a handle and is told to stop when its context stops. The VM's own script
has a root context; `bun test --isolate`, worker termination and VM
teardown stop the root context's handles through the same list. A
`ContextId` is the C++ `ScriptExecutionContextIdentifier`; Rust
allocates none. Every C++ `ScriptExecutionContext` is made together with
its Rust half.
2. **`JSModuleGraph`.** A module loader of its own whose module scope
(an overlay over the global lexical environment) holds the host's
`globals`, the loader and the graph. Graphs with the same `globals`
names share one overlay `SymbolTable`, which is what JSC keys shared
module executables on.
3. **The current context rides the async context.** Entering a graph
pushes a frame shaped like an `AsyncLocalStorage` frame whose storage is
the graph; native code finds the current graph by walking the chain to
the first such frame. Until a graph has been constructed every lookup is
one flag test. Native functions that start work take one `&JsThread`
(the global and the calling script's context) instead of a bare global.
4. **Work that returns to the JS thread says whose script it
continues.** A `Task` carries its context (the `Taskable` trait makes
every task type say so) and the dispatcher releases a task whose context
has stopped. Beyond that there are three places where native code
reaches script and a disposed graph is turned away, instead of one per
completion: wrapped callbacks and DOM listeners
(`shouldDropCallbackOfStoppedModuleGraph`), settling a promise
(`JSPromise::resolve` / `reject`), and `JSValue::call`.
5. **Native dispatchers that report errors themselves run inside their
owner's context** for the whole dispatch: `Bun.serve`'s request paths
and the `node:http` request path, `Bun.listen` / `Bun.connect` handlers
(`Handlers::enter`), UDP callbacks, and the server's websocket entry
points. That is what gives the owner an error nobody threw, and a thrown
value a dispatcher has already unwrapped.
6. **Callbacks script stores on something long-lived** continue the
graph whose script stored them: most are stored with the async context,
as before; the `node:http` server socket's `ondata` / `ondrain` /
`onclose` and `RedisClient`'s `onconnect` / `onclose` are stored with
only the frame that entered the graph, and bare outside a graph, so that
without a graph they run exactly as they did. Long-lived JS objects that
open things later (`http.Agent`, `Bun.SQL`, `PerformanceObserver`)
remember the frame of the graph they were made in and do that work in
it. `Agent.createSocket` hands a socket that came through a proxy tunnel
to the waiting request in the requester's frame when the tunnel's
callbacks ran in another graph's context.
7. **CommonJS.** A `JSCommonJSModule` has one `m_moduleGraph`. Its
wrapper is evaluated normally and re-created over the graph's overlay;
`CommonJS.ts` reads the module's require map once and passes it down.
8. **Builtin modules are evaluated in the realm's context** whoever
loads them first, so what `node:http` and friends set up at load is
never a graph's. The HTTP `date` cache is keyed by the second instead of
cleared by a timer, because a timer belongs to whoever set it.
9. **Leftover code is refused where work starts, not where it
completes.** Native entry points that would put something on the network
ask the calling script's context first and return a pending promise or
an object that never connects (`fetch`, `Bun.connect` / `Bun.listen`,
UDP, `WebSocket`, the Redis client's `connect()`, the functions that put
an S3 request on the HTTP thread); a DNS answer for a stopped context
settles nothing. Four places in Node's and Bun's own JavaScript that
start or announce something from `process.nextTick()` check for a
disposed graph: `'listening'` in `node:net` and `node:http`, a child's
spawn in `node:child_process`, and the function both SQL drivers dial
through.
10. **N-API.** Async work and threadsafe-function completions queued by
a graph run in its context. After dispose they still run, since the
addon owns memory only it can free, but the functions that run script
return `napi_cannot_run_js`, and resolving a deferred frees it and
settles nothing. A threadsafe function is its maker's.
11. **Errors.** `JSC::Exception` records the async context it was first
thrown in (oven-sh/WebKit#689), and
`Bun__ModuleGraph__handleUncaughtException` reads the graph from it; a
bare value is attributed to the context that is current where it is
reported. `process.nextTick`'s loop no longer catches in JS: what a tick
throws reaches `JSNextTickQueue::drain` as it was thrown, with the
tick's frame still current; `drain` reports it there, restores the async
context and resumes the queue, so the order of ticks, handlers and
microtasks is unchanged. The process's `uncaughtException` /
`unhandledRejection` handlers run in the realm's context whichever graph
failed.
12. **`Bun.cron()`.** A tick's promise reactions own the job through a
`NativePromiseContext` cell, so a tick still waiting when its graph is
disposed, or settled by the host afterwards, neither leaks nor touches a
freed job.

Behaviour that changes for programs that never construct a
`Bun.ModuleGraph` (each compared with the last release):

- `bun test --isolate` is stricter: more of what a file left running is
stopped at the swap: `Bun.cron` jobs, S3 multipart uploads (their
promises reject with `AbortError`), `Bun.FetchSession` idle sockets,
N-API threadsafe functions' hold on the loop, and a `Bun.build()` still
in flight (its promise stays pending). Handles armed by the outgoing
file's close handlers are stopped at the same swap. A `crypto.subtle`
promise left pending across the swap no longer settles in the next file.
- An S3 multipart upload whose final commit fails now sends the abort
request, as one that fails earlier already did.
- A closed `RedisClient` that had subscriptions no longer keeps the
process alive.
- An `fs.promises.open()` whose result is never delivered (its realm was
retired, its worker terminated) closes the descriptor instead of leaking
it. A `Bun.write()` promise in flight at an `--isolate` swap, and an S3
stream upload whose pump promise is collected unsettled, are released.
- `listener.stop()` followed by `listener.stop(true)` closes the
accepted connections (the second call used to do nothing), and
`listener.data` is cleared once a stopped listener's last connection
closes.
- `BroadcastChannel` drops its hold on the event loop when its context
stops.
- An uncaught error thrown from a `process.nextTick` callback is printed
from the exception's throw site, as one from a timer already was; a
thrown non-`Error` value is printed with its source frame.
- An `enterWith()` made inside an `uncaughtException` /
`unhandledRejection` handler ends with the handler.
- Windows: a named-pipe client still connecting when its context stops
is cancelled.
- `"ModuleGraph" in Bun` is true.

What async context an `uncaughtException` handler, a `node:http` socket
listener or an `http.Agent` request callback sees is the same as in the
last release; `test/js/node/async_hooks/AsyncLocalStorage.test.ts` pins
it, with node's answers as the expectations. The WebKit pin is the one
`main` already uses.

### How did you verify your code works?

CI on every platform, and targeted runs locally on a debug+ASAN build;
GC behaviour on release builds.

- `test/js/bun/module-graph/`: `module-graph.test.ts` (the API, module
semantics, CommonJS, error attribution and `onError`),
`module-graph-isolation.test.ts` (what a graph owns, what dispose
closes, what leftover code can and cannot do, per kind of I/O),
`module-graph-io.test.ts` (the context following code; a test that walks
some fifty event sources and checks who is given what their listener
throws; an error nobody threw; two graphs on one connection; handlers of
a disposed graph on a client of the host's; a request through the host's
`Agent`, direct and through a CONNECT proxy),
`module-graph-matrix.test.ts` (kinds of work × who started it × when it
is disposed), `module-graph-workers.test.ts` (graphs × workers and every
order of `terminate()` / `dispose()` / `process.exit()`),
`module-graph-compile.test.ts` (single-file executables),
`module-graph-gc.test.ts` (what keeps a graph alive and that nothing
else does), `module-graph-callbacks.test.ts`.
- New tests were checked to fail on the build without the change they
cover.
- Outside that directory:
`test/js/node/async_hooks/AsyncLocalStorage.test.ts` (which store an
`uncaughtException` handler reads, for a callback that throws directly
and one that throws inside a store of its own; `node:http` server socket
and client request events; an `Agent` has no new visible property),
`test/js/node/process/process-nexttick.test.js` (a tick that throws does
not stop the ticks after it, and the order),
`test/cli/test/isolation.test.ts` (what a leaked listener's close
handler opens is closed before the next file; the default DNS resolver
answers in every file), `test/napi/napi.test.ts` (completions for a
graph), `test/js/web/websocket/websocket.test.js` and
`test/bake/dev/production.test.ts` (a `WebSocket` made inside a
ShadowRealm / while a page is prerendered),
`test/integration/bun-types/fixture/module-graph.ts`.
- Two existing tests changed. `test/js/bun/test/bun_test.test.ts`: a
string thrown from a tick is now printed with its source frame, like the
string thrown from `describe()` a few lines above it in the same
snapshot. `test/js/bun/http/serve-pending-promise-abort-leak.test.ts`
"client abort of a streaming Response releases the body stream it held"
gives each collection in its retry loop a fresh turn, as the h2
stream-release tests do since #40966: `WeakRef.prototype.deref()` keeps
its target alive until the end of the job, and every collection after
the first ran in the same job as a `deref()`, so its 20 passes were one.
On this branch's x64-asan build that first pass missed: nothing
references the last stream (no incoming edge, no root in a heap
snapshot), but one stack word in an AddressSanitizer redzone of JSC's
live `runInternalMicrotask` frame still holds a callee-saved register
the release path itself pushed while the stream was in it; zeroing that
word in a debugger frees the stream. Built from `main` the same push
lands 288 bytes away, on a local's slot that is rewritten.
- `cargo clippy`.

Known:

- The "TypeScript types" check fails for a reason unrelated to this
change (#42230).
- Three tests are `todo`. `module-graph-isolation.test.ts`
"node:cluster: what a worker it forked tells the primary…": in about 2%
of runs the fixture's probe of the worker's port right after `dispose()`
connects instead of being refused, and the fixture then never exits;
whether the primary's listener for the worker is closed inside
`dispose()` or a turn later is not established.
`module-graph-gc.test.ts` "a repeating timer keeps its graph alive;
clearing it lets the graph go" is a todo on macOS x64 only, where it
fails on every build: its heap snapshot shows the graph's cycle with
nothing in the heap and no root reaching it, and what holds it is not
established. "a dropped graph whose module keeps a FileHandle open is
collected" is a todo on Linux aarch64 only, where it fails on every
build and nowhere else (it passes on that build under emulation); what
holds the graph there is not established.

---------

Co-authored-by: Dylan Conway <dylan.conway567@gmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant