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.

[bizob2828]

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.

That's fine but just a simple application that can expose it would be helpful.

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](https://github.com/newrelic/node-newrelic/blob/77621fbb33169bad90165de95f11c3c4a1b7fc94/lib/transaction/tracer/index.js#L68-L77)
  
  
      Lines 68 to 77
    in
    [77621fb](/newrelic/node-newrelic/commit/77621fbb33169bad90165de95f11c3c4a1b7fc94)
  
  
  
  
  
      
        
         // 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](https://github.com/newrelic/node-newrelic/blob/77621fbb33169bad90165de95f11c3c4a1b7fc94/lib/shim/shim.js#L1192)
  
  
       Line 1192
    in
    [77621fb](/newrelic/node-newrelic/commit/77621fbb33169bad90165de95f11c3c4a1b7fc94)
  
  
  
  
  
      
        
         this.tracer.setSegment({ segment, transaction })
  

• Globals _fatalException:

    [node-newrelic/lib/instrumentation/core/globals.js](https://github.com/newrelic/node-newrelic/blob/77621fbb33169bad90165de95f11c3c4a1b7fc94/lib/instrumentation/core/globals.js#L30)
  
  
       Line 30
    in
    [77621fb](/newrelic/node-newrelic/commit/77621fbb33169bad90165de95f11c3c4a1b7fc94)
  

this may be an issue but hard to tell without a reproduction.

         shim.setActiveSegment(null)

• Domain instrumentation:

    [node-newrelic/lib/instrumentation/core/domain.js](https://github.com/newrelic/node-newrelic/blob/77621fbb33169bad90165de95f11c3c4a1b7fc94/lib/instrumentation/core/domain.js#L23)
  
  
       Line 23
    in
    [77621fb](/newrelic/node-newrelic/commit/77621fbb33169bad90165de95f11c3c4a1b7fc94)
  

this instrumentation should not be in play for a majority of applications.

         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.

Yea cleaning up context when transactions end defeats the purpose of async local storage, it should be doing this automatically.

[atma]

Yea cleaning up context when transactions end defeats the purpose of async local storage, it should be doing this automatically.

I think there's a misunderstanding. We're not asking to clear the ALS store or stop context propagation, that would indeed defeat its purpose. We're saying the references inside the Context object (_transaction, _segment) should be nullified after transaction.end() completes. The Context stays in ALS, the propagation keeps working, but the finished Transaction and its TraceSegment tree can be GC'd.

Proposed fix (still pure theory) - extend _cleanUnneededReferences() to also release the transaction/segment references from the Context stored in ALS. Or enterWith(new Context()) at transaction end.

Why this matters now: under the old async_hooks implementation, enterWith() mutated the existing execution resource in-place, the next request simply overwrote the old reference. Under AsyncContextFrame, since v24.x, enterWith() allocates a new frame each time, and every Promise created in that scope captures the frame via V8's ContinuationPreservedEmbedderData. In SSR apps with hundreds of Promises per request, that's hundreds of copies holding references to finished transactions that can't be GC'd.

Regarding reproduction - sorry, but we can't expose production apps, but any Express SSR app with significant async activity on Node.js 24 should exhibit this under sustained load. Our setup is standard Express + SSR React + excessive axios-like communication, all with default automatic New Relic instrumentation.

[jsumners-nr]

sorry, but we can't expose production apps

This has not been asked. We do not want to review anyone's "production apps."

any Express SSR app with significant async activity on Node.js 24 should exhibit this under sustained load.

What does such an application look like? What is the definition of "significant"? A minimal reproduction will answer these questions, allow for further investigation, and hopefully lead to a solution.