Memory leak with Node.js 24 due to AsyncContextFrame + enterWith()

[atma]

Memory leak with Node.js 24 due to AsyncContextFrame + enterWith()

Description

Node.js 24 changed the default AsyncLocalStorage implementation to use AsyncContextFrame (via nodejs/node#55552). Under this new default, the enterWith() method — which the New Relic agent relies on — causes memory leaks in long-running applications.

The New Relic agent calls enterWith() directly in its context manager:

node-newrelic/lib/context-manager/async-local-context-manager.js

Line 43 in 83adcc4

this._asyncLocalStorage.enterWith(newContext)

setContext(newContext) {
  this._asyncLocalStorage.enterWith(newContext)
}

With the new AsyncContextFrame implementation, enterWith() behaves differently than it did under the previous AsyncLocalStorage implementation. Specifically, AsyncResource instances no longer reflect enterWith() mutations made after their construction — they snapshot the storage at construction time. This behavioral change, combined with the frequent enterWith() calls the agent makes on every instrumented function, leads to context objects being retained longer than expected and accumulating in memory.

There is an upstream Node.js issue tracking this behavioral change: nodejs/node#58204.

Additionally, enterWith() is marked as Stability: 1 - Experimental in the [Node.js v24 documentation](https://nodejs.org/docs/latest-v24.x/api/async_context.html#asynclocalstorageenterwithstore), which suggests it may not be the most reliable foundation for context propagation going forward.

Steps to reproduce

1. Run any Node.js application instrumented with newrelic on Node.js v24.0.0+
2. Generate sustained traffic over time
3. Observe heap memory growing continuously without being reclaimed by GC

The core issue can be demonstrated in isolation with this minimal script (from nodejs/node#58204):

const { AsyncLocalStorage, AsyncResource } = require('async_hooks')
const { strictEqual } = require('assert')

const storage = new AsyncLocalStorage()
storage.enterWith(1)
const ar = new AsyncResource('test')
ar.runInAsyncScope(() => {
  storage.enterWith(2)
  ar.runInAsyncScope(() => strictEqual(storage.getStore(), 2))
})
// Fails on Node 24: expected 2 but got 1

Expected behavior

Memory usage should remain stable over time, with context objects being properly garbage-collected after their associated transactions complete.

Actual behavior

Heap memory grows continuously. Context objects set via enterWith() are retained because the AsyncContextFrame implementation snapshots storage at AsyncResource construction time rather than reflecting later enterWith() mutations.

Environment

• Node.js version: v24.0.0+
• New Relic agent version: tested with v12.x and 13.x
• OS: any

Temporary workaround

Starting the application with the --no-async-context-frame flag reverts to the previous AsyncLocalStorage implementation and avoids the leak:

node --no-async-context-frame app.js

Suggested fix

Consider replacing the enterWith() usage in async-local-context-manager.js with AsyncLocalStorage.run(), which is the stable API and works correctly under both the old and new AsyncContextFrame implementations. Alternatively, the Node.js docs suggest using tracingChannel as a modern replacement for patterns relying on enterWith() + AsyncResource.

Related issues

• nodejs/node#55552 — PR making AsyncContextFrame the default
• nodejs/node#58204 — AsyncResource no longer respects enterWith() under AsyncContextFrame
• Node.js v24 docs: enterWith() stability — marked as Experimental

[Newrelic-Boomi]

https://new-relic.atlassian.net/browse/NR-541152

[bizob2828]

@atma thanks for the report.

It's worth noting that I don't think nodejs/node#58204 applies to our agent. We are not using AsyncResource, just AsyncLocalStorage.

Additionally, enterWith() is marked as Stability: 1 - Experimental in the [Node.js v24 documentation](https://nodejs.org/docs/latest-v24.x/api/async_context.html#asynclocalstorageenterwithstore), which suggests it may not be the most reliable foundation for context propagation going forward.

We are part of the working group that discusses theses APIs. The reason parts of AsyncLocalStorage as well as TracingChannel aren't stable is vendors like us are really the big consumers of these APIs ad we haven't had enough soak time to deem APIs, or methods stable.

With all that being said, do you mind providing a reproduction case using a real application? Looking at our codebase the only instrumentation that uses this code path is undici, but as I mentioned above we aren't using AsyncResource with AsyncLocalStorage, but would be good to see a real application exhibiting this leak to properly triage and possibly fix.

[atma]

Thanks for the quick response @bizob2828

It is difficult to have minimal reproduction, the leak is a slow accumulation and it requires sustained high traffic over many hours, with Node.js 24/16 GB RAM/~40K rpm servers crashing with OOM after ~20-24h.

You're right that the agent doesn't use AsyncResource directly. However, the core behavioral change in AsyncContextFrame affects enterWith() itself, independently of AsyncResource. Under the new implementation, each enterWith() call allocates a new frame (a copy-on-write Map) via setContinuationPreservedEmbedderData, instead of mutating the current execution resource in-place as the old async_hooks implementation did. We referenced #58204 to illustrate the broader behavioral shift, not to claim the agent uses AsyncResource.

The enterWith() call in setContext() is reached from more than just undici. Here are the callsites we traced:

• tracer.setSegment():

  node-newrelic/lib/transaction/tracer/index.js

  Lines 68 to 77 in 77621fb

  	// TODO: update to setNewContext or something like that
  	function setSegment({ transaction, segment } = {}) {
  	const context = this.getContext()
  	const newContext = context.enterSegment({
  	transaction: transaction !== undefined ? transaction : context.transaction,
  	segment: segment !== undefined ? segment : context.segment
  	})
  	this._contextManager.setContext(newContext)
  	}

• shim.setActiveSegment():

  node-newrelic/lib/shim/shim.js

  Line 1192 in 77621fb

  this.tracer.setSegment({ segment, transaction })

• Globals _fatalException:

  node-newrelic/lib/instrumentation/core/globals.js

  Line 30 in 77621fb

  shim.setActiveSegment(null)

• Domain instrumentation:

  node-newrelic/lib/instrumentation/core/domain.js

  Line 23 in 77621fb

  shim.setActiveSegment(shim.getSegment(this))

Looks like any code path reaching tracer.setSegment() triggers enterWith().

We believe the critical issue is that transaction.end() does not clear the AsyncLocalStorage context. It calls _cleanUnneededReferences() which only nulls userErrors and exceptions, but the Context object (holding the finished Transaction and its TraceSegment tree) remains in the ALS frame.
Under the old async_hooks implementation, this was mostly harmless — the context lived on the execution resource and would be overwritten on the next request. Under AsyncContextFrame, the completed transaction's context persists in its frame, and every new Promise created in that execution scope copies the frame (V8's ContinuationPreservedEmbedderData propagation). For SSR applications creating hundreds of promises per request, this means hundreds of copies of frames holding references to finished transactions.