Skip to navigation

Node.js runtime upgraded to Node 22

Platform 6.6.0 upgrades its supported Node.js runtime from Node 20 to Node 22. Most deployments need no changes. If you run custom apps, custom adapters, or other custom code, check it against Node 22 before you upgrade. Two changes cover the vast majority of issues:

  • crypto.createCipher and crypto.createDecipher from node:crypto are removed in Node 22.
  • Native add-ons might need to be rebuilt with npm rebuild on Node 22.

This change doesn’t affect Itential Platform Cloud instances.

Before you begin

This change affects you if you:

  • Run Itential Platform 6 on-prem and want to upgrade to Platform 6.6.0 or later
  • Deploy custom apps, custom adapters, or other custom code alongside Platform

What changed

How you get Node 22 depends on how you install Platform:

  • Platform images (Docker): The images for Platform 6.6.0 and later bundle Node 22. Everything running in the container, including your custom code, runs on Node 22 when you take the new image. There is no way to keep running Node 20 on these images.
  • Platform RPM: The RPM doesn’t bundle Node. It uses the Node version installed on the host. Before you install the Platform 6.6.0 or later RPM, upgrade the host to Node 22.

Validate your custom code

Before upgrading to Platform 6.6.0 or later:

1

Identify custom code

Identify all custom apps, adapters, and other custom code deployed in your environment.

2

Rebuild native addons

With Node 22 installed, run npm rebuild on any custom apps or adapters that have native addons.

3

Check for removed functions

Confirm your custom code doesn’t call crypto.createCipher or crypto.createDecipher. Replace them with crypto.createCipheriv and crypto.createDecipheriv.

4

Review the other changes

Review Other changes to check for and confirm none apply to your code or its dependencies.

5

Test in a non-production environment

Test your custom code against Node 22 in a non-production environment.

Other changes to check for

The following checklist covers other changes between Node 20 and Node 22 that are most likely to affect custom apps and adapters. The first two items under “More likely to cause errors” cover most cases.

More likely to cause errors

AreaChangeWhat to do
cryptocreateCipher and createDecipher are removed. They now throw at runtime instead of logging a warning.Replace with createCipheriv and createDecipheriv.
Native addonsThe Node module ABI version changed, so .node files built for Node 20 fail to load with an error like The module '/path/to/xyz.node' was compiled against a different Node.js version.Run npm rebuild while Node 22 is active.
netserver.maxConnections = 0 no longer means “no limit.” Node now applies it literally, and the server silently rejects every incoming connection.Remove the setting (the default is unlimited) or set a specific positive number.

More likely to change runtime behavior

The atime, mtime, ctime, and birthtime properties on Stats objects are now lazy-loaded and no longer appear when you enumerate the object, for example with spread syntax or JSON.stringify(). To keep the old behavior, copy them explicitly:

{ ...stats, mtime: stats.mtime, atime: stats.atime, ctime: stats.ctime, birthtime: stats.birthtime }

Node 22 defines a global Iterator. Your own code is unlikely to be affected, but polyfills that patch Iterator.prototype unconditionally can throw TypeError: Cannot redefine property. Check your dependencies for iterator-helper polyfills such as es-iterator-helpers or core-js iterator shims.

Node 22 defines a global WebSocket. Guarded assignments like if (!global.WebSocket) { global.WebSocket = require('ws') } now silently do nothing, so the service might use Node’s built-in implementation instead of the one it expected. Check your dependencies for this pattern.

URL and URLSearchParams instances can no longer be cloned or transferred. Passing one through a structured clone, for example MessagePort.postMessage() in worker_threads, throws a DataCloneError. Convert the object to a string with toString() before sending it, and reconstruct it on the receiving end.

The bundled llhttp HTTP parser is stricter and more spec-compliant. Malformed input that Node previously tolerated, such as invalid characters in header or URL fields or embedded raw \n in headers, is now rejected with a parse error. Confirm that clients sending traffic to your service’s HTTP server still parse cleanly.

When you use both response.setHeader() and response.writeHead(), duplicate headers are now preserved instead of collapsed. Avoid mixing the two calls, or deduplicate headers before passing them.

The default highWaterMark increased from 16 KiB to 64 KiB, so streams buffer more data by default. Check services with tight memory budgets, or tests that assert exact chunk sizes or counts on data events.

Node 22 also adds many runtime deprecations. These don’t change behavior but can produce noisy deprecation warnings in your logs.

The Node.js project is the source of truth for changes between Node versions. For the full list, see the Node.js 21 and Node.js 22 release notes and the Node.js deprecations list.

For general upgrade prerequisites, see Upgrade to the latest version of Platform 6.