Skip to main content
dd-trace v4 drops support for Node.js 14, removes the orphanable option, drops jest-jasmine2 support, and removes support for older Next.js versions. This guide covers all breaking changes and the steps to upgrade.

​
Breaking changes

Node.js 14 is no longer supported. Node.js 14 reached end-of-life in April 2023. dd-trace v4 requires Node.js 16 or later.

​
Node.js version requirement

dd-trace v4 requires Node.js >= 16. If your application runs on Node.js 14, you must upgrade Node.js before upgrading dd-trace.

​
orphanable option removed

The orphanable span option has been removed. This option was only used internally for a single integration that has since been removed and was never useful for manual instrumentation. To create a root span without a parent in manual instrumentation, pass childOf: null directly: 
// Before (v3) — orphanable option
tracer.trace('web.request', { orphanable: true }, (span) => {
  // ...
})

// After (v4) — use childOf: null instead
tracer.trace('web.request', { childOf: null }, (span) => {
  // Creates a root span even when a parent exists in scope
})

​
jest-jasmine2 support removed

The Jest integration no longer supports jest-jasmine2 as a test runner. Jest changed its default test runner to jest-circus approximately two years before this removal. If your Jest configuration explicitly sets testRunner: 'jest-jasmine2', you must switch to jest-circus. Update your Jest configuration:
jest.config.js
module.exports = {
  // Before (v3)
  // testRunner: 'jest-jasmine2',

  // After (v4) — jest-circus is the default, no explicit config needed
  // Or set it explicitly:
  testRunner: 'jest-circus/runner',
}

​
Older Next.js versions no longer supported

dd-trace v4 supports only Next.js 10.2 and later. If your application uses an older version of Next.js, you must upgrade Next.js before upgrading dd-trace. Check your Next.js version: 
npm show next version
# or
cat package.json | grep next

​
Upgrade steps

1

Upgrade Node.js to 16 or later

dd-trace v4 requires Node.js 16 or later. Update your runtime before upgrading the package.
node --version
# v16.x.x or later
Update any .nvmrc, .node-version, Dockerfile, or CI configuration files that pin your Node.js version.
2

Switch from jest-jasmine2 to jest-circus (if applicable)

If your Jest configuration uses jest-jasmine2, update it to use jest-circus before installing dd-trace v4.Remove any explicit testRunner: 'jest-jasmine2' setting from your Jest configuration. jest-circus is the default and no explicit configuration is needed.
3

Upgrade Next.js to 10.2 or later (if applicable)

If your application uses Next.js older than 10.2, upgrade it:
npm install next@latest
4

Remove orphanable option usage

Search your codebase for any uses of the orphanable option and replace them with childOf: null:
grep -r 'orphanable' .
For each occurrence, replace with { childOf: null } in your span options.
5

Install dd-trace v4

npm install dd-trace@4
Or with yarn:
yarn add dd-trace@4
6

Run your test suite

npm test

​
Version compatibility table

dd-trace versionNode.js requirementStatus
v5 (current)>= 18Current
v4>= 16EOL
v3>= 14EOL
v2>= 12EOL
For any issues related to migrating, open an issue on the dd-trace-js GitHub repository or contact Datadog support.

Build docs developers (and LLMs) love

Get started for freeTalk to us