AsyncLocalStorage

AsyncLocalStorage

Last updated Apr 23, 2026

Background

Note

For compatibility dates of 2026-08-04 or later, Workers enables both nodejs_compat and nodejs_compat_v2 by default. These flags are not used for these compatibility dates. Existing projects do not need to remove them when updating their compatibility date. For earlier dates, add nodejs_compat to your Wrangler configuration file to opt in. For instructions to turn off Node.js compatibility, refer to the Node.js compatibility flag.

Cloudflare Workers provides an implementation of a subset of the Node.js AsyncLocalStorage ↗︎ API for creating in-memory stores that remain coherent through asynchronous operations.

Constructor

import { AsyncLocalStorage } from "node:async_hooks";

const asyncLocalStorage = new AsyncLocalStorage();

new AsyncLocalStorage() : AsyncLocalStorage
Returns a new AsyncLocalStorage instance.

Methods

getStore() : any
Returns the current store. If called outside of an asynchronous context initialized by calling asyncLocalStorage.run(), it returns undefined.
run(storeany, callbackfunction, ...argsarguments) : any
Runs a function synchronously within a context and returns its return value. The store is not accessible outside of the callback function. The store is accessible to any asynchronous operations created within the callback. The optional args are passed to the callback function. If the callback function throws an error, the error is thrown by run() also.
exit(callbackfunction, ...argsarguments) : any
Runs a function synchronously outside of a context and returns its return value. This method is equivalent to calling run() with the store value set to undefined.

Static Methods

AsyncLocalStorage.bind(fn) : function
Captures the asynchronous context that is current when bind() is called and returns a function that enters that context before calling the passed in function.
AsyncLocalStorage.snapshot() : function
Captures the asynchronous context that is current when snapshot() is called and returns a function that enters that context before calling a given function.

Examples

Fetch Listener

import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();
let idSeq = 0;

export default {
  async fetch(req) {
    return asyncLocalStorage.run(idSeq++, () => {
      // Simulate some async activity...
      await scheduler.wait(1000);
      return new Response(asyncLocalStorage.getStore());
    });
  }
};

Multiple stores

The API supports multiple AsyncLocalStorage instances to be used concurrently.

import { AsyncLocalStorage } from 'node:async_hooks';

const als1 = new AsyncLocalStorage();
const als2 = new AsyncLocalStorage();

export default {
  async fetch(req) {
    return als1.run(123, () => {
      return als2.run(321, () => {
        // Simulate some async activity...
        await scheduler.wait(1000);
        return new Response(`${als1.getStore()}-${als2.getStore()}`);
      });
    });
  }
};

Unhandled Rejections

When a Promise rejects and the rejection is unhandled, the async context propagates to the 'unhandledrejection' event handler:

import { AsyncLocalStorage } from "node:async_hooks";

const asyncLocalStorage = new AsyncLocalStorage();
let idSeq = 0;

addEventListener("unhandledrejection", (event) => {
    console.log(asyncLocalStorage.getStore(), "unhandled rejection!");
});

export default {
    async fetch(req) {
        return asyncLocalStorage.run(idSeq++, () => {
            // Cause an unhandled rejection!
            throw new Error("boom");
        });
    },
};