Specify a compatible Node engine version in package.json

[VxJasonxV]

Bug Description

The Node version in engines {} specifies any version greater than or equal to Node 20.15:

n8n/package.json

Line 6 in 321d6de

"node": ">=20.15",

When n8n is deployed on a system where the version of Node used is dynamic (e.g. virtually every PaaS, managed app host, etc.), it always picks the latest stable release of Node, which as of this writing is Node 23.0.0. Later in n8n's own code, execution aborts because n8n doesn't support Node 23:

n8n/packages/cli/bin/n8n

Lines 27 to 32 in 321d6de

	if (
	(ENFORCE_MIN_NODE_VERSION && !gte(nodeVersion, MINIMUM_SUPPORTED_NODE_VERSION)) ||
	![18, 20, 22].includes(major(nodeVersion))
	) {
	console.log(`
	Your Node.js version ${nodeVersion} is currently not supported by n8n.

Please update the Node engine specification to match your in-application version logic's needs.

To Reproduce

1. Deploy n8n onto your favorite application host.
2. Assuming a successful build, run the application, observe the output:

==> Requesting Node.js version >=20.15
==> Using Node.js version 23.0.0 via package.json
==> Running 'pnpm run start'

> n8n-monorepo@1.63.0 start:default
> cd packages/cli/bin && ./n8n


	Your Node.js version 23.0.0 is currently not supported by n8n.
	Please use Node.js v18.17.0 (recommended), v20, or v22 instead!

 ELIFECYCLE  Command failed with exit code 1.

Expected behavior

A successfully running deployment of n8n, using an appropriate version of Node, in environments where Node is dynamically installed based off package.json definition.

Operating System

Debian Bookworm 12

n8n Version

1.64.0

Node.js Version

23.0.0

Database

SQLite (default)

Execution mode

main (default)

[Joffcom]

Hey @VxJasonxV,

We have created an internal ticket to look into this which we will be tracking as "GHC-330"

[joepolask86]

How is this affecting my n8n on Render.

ELIFECYCLE  Command failed with exit code 1.
==> Requesting Node.js version >=20.15
==> Using Node.js version 23.0.0 via /opt/render/project/src/package.json
==> Docs on specifying a Node.js version: https://render.com/docs/node-version
==> Running 'pnpm run start'

n8n-monorepo@1.63.0 start /opt/render/project/src
run-script-os
n8n-monorepo@1.63.0 start:default
cd packages/cli/bin && ./n8n
Your Node.js version 23.0.0 is currently not supported by n8n.
Please use Node.js v18.17.0 (recommended), v20, or v22 instead!

 ELIFECYCLE  Command failed with exit code 1.
 
 I can't build stuff on N8N
 
Bad Gateway
Request ID: 8d53cdbde42a1ba5-MAD

[VxJasonxV]

You can specify a specific version of Node to use with a higher precedence than the package.json definition.

I filed this because you shouldn't have to, but there are workarounds available.

You are not blocked.

[VxJasonxV]

n8n/packages/cli/package.json

Line 45 in 0e74dd0

"node": ">=18.17 <= 22"

<= 22 is interesting, because it will match 22.0.0, but not the probably much more desired current release in that series 22.10.0 as of this writing, nor any of the other updates in between. Wouldn't that be better expressed as < 23?

[netroy]

from the testing I did, <= 22 matched all versions of 22.x

[VxJasonxV]

==> Using Node.js version 22.10.0 via environment variable NODE_VERSION
==> Docs on specifying a Node.js version: https://render.com/docs/node-version
==> Running 'pnpm run start'
> n8n-monorepo@1.64.0 start /opt/render/project/src
> run-script-os
> n8n-monorepo@1.64.0 start:default
> cd packages/cli/bin && ./n8n
No encryption key found - Auto-generated and saved to: /opt/render/.n8n/config
(node:138) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
Initializing n8n process
n8n ready on 0.0.0.0, port 5678
Migrations in progress, please do NOT stop the process.
[migration output trimmed]
Version: 1.64.0
Editor is now accessible via:
http://localhost:5678/

==> Using Node.js version 23.0.0 via environment variable NODE_VERSION
==> Docs on specifying a Node.js version: https://render.com/docs/node-version
==> Running 'pnpm run start'
> n8n-monorepo@1.64.0 start /opt/render/project/src
> run-script-os
> n8n-monorepo@1.64.0 start:default
> cd packages/cli/bin && ./n8n
Your Node.js version 23.0.0 is currently not supported by n8n.
Please use a Node.js version that satisfies the following version range: >=18.17 <= 22
 ELIFECYCLE  Command failed with exit code 1.

Well, I can't argue with that even if that's not my understanding of semver. My understanding is that unspecified minor or patch versions are supposed to be expanded to 0, and <= 22.0.0 shouldn't match 22.10.0. That said, for purposes of this issue I'm not going to argue it should be different, because it's clearly getting past the evaluation.

Thank you very much for this change.

[edit]
I see, my ".0 expansion" understanding wasn't correct:

Hyphen Ranges

If a partial version is provided as the first version in the inclusive range, then the missing pieces are replaced with zeroes.

If a partial version is provided as the second version in the inclusive range, then all versions that start with the supplied parts of the tuple are accepted, but nothing that would be greater than the provided tuple parts.

The first version is expanded to zeros, the second version is expanded to *s. Got it, that's where my logic broke down.

Again, thank you.

[VxJasonxV]

I had a customer report that they were still affected by this. They were previously running a commit prior to its inclusion but updating their fork to the latest commit as of yesterday, their service was still trying to load Node 23, and encountering the same error.

Looking back over this issue again I assume it's because the change was only made to the cli sub-directory, but the change should have been made at the project's root. I can only speak about the behavior for my employer (Render), but I anticipate the behavior would be similar for most other service providers;

When the whole application is imported into a service on Render, the root package.json is evaluated. That file's engines section still specifies a version of Node >= 20.15 (

n8n/package.json

Line 6 in f4ca4b7

"node": ">=20.15",

). This is the declaration that Render considers when picking a version of Node, and as a result will still pick a 23 series release.

The fix made to the engines section in 3b32ad0 should have applied to the root directory's package.json file, not the cli sub-directory's package.json.

(Wild speculation: Perhaps it should have been done to both? I don't know if there is a situation where the user would only have the CLI deployed and not the whole repo.)

[netroy]

We actually prefer to not define a max nodejs version at the root level because we are constantly working to make sure that n8n is ready for all future stable versions of node.
That way if any contributor wants to develop on node 23, we are likely to catch issues early on.

I don't know how your builds are setup, but if you are still using pnpm, I'd recommend using pnpm deploy like we do for our custom images.

[VxJasonxV]

Builds are dynamic based on a handful of factors, but for the Node version it is dependent on (in descending order of precedence):

1. An environment variable named NODE_VERSION
2. A file in the root directory named .node-version
3. A file in the root directory named .nvmrc, and absent all those;
4. The contents of the engines: {node:} section of the root directory's package.json

Using pnpm, npm, or any other build tool is irrelevant because the Node version selection will have already happened before the build command is even run. The runtime version/environment is selected first based off the aforementioned rules, and then the build/run execution takes place inside of that. The image you linked to explicitly specifies Node 20 as the very first step, which is the exact mitigation analogous the point I'm making here.

I don't agree with the statement that the current solution is ok and contributor friendly, because this project has logic that exits when used under Node 23 (

n8n/packages/cli/bin/n8n

Lines 29 to 33 in fd3254d

	console.error(`
	Your Node.js version ${nodeVersion} is currently not supported by n8n.
	Please use a Node.js version that satisfies the following version range: ${supportedNodeVersions}
	`);
	process.exit(1);

), any contributor has to undo/modify that anyway.

[netroy]

the Node version selection will have already happened before the build command is even run.

That's a valid point. Let me get back to you tomorrow.

[VxJasonxV]

Because I don't want to force you into a Render-specific solution here, I did research on a handful of service hosts to see how they manage this in order to approach this with as vendor-agnostic a solution as possible.

I previously laid out how Render determines the Node Version to use ( #11313 (comment), https://docs.render.com/node-version ), a descending order list but Nº1 is Render specific, Nºs 2 and 3 are not files that currently exist in this repository, so Nº4 (package.json engines:{node:}) is used when deploying this application assuming no end-user override. Render would default to the latest LTS if not specified.

Heroku exclusively uses the engines section of package.json ( https://devcenter.heroku.com/articles/nodejs-support#specifying-a-node-js-version ) and that likely means that deploying n8n on Heroku has similar failures as we (Render) have been experiencing.

Vercel also consults the engines section which if specified will override what is selected in the web interface, but if I'm understanding their documentation correctly they cap at the latest 20.x series release ( https://vercel.com/docs/functions/runtimes/node-js/node-js-versions ), so I think they will not be impacted because they won't run version 23 (nor even 22).

Fly.io uses Docker ( https://fly.io/docs/machines/flyctl/fly-machine-run/ ), and Railway uses Docker or nixpacks (https://docs.railway.com/reference/deployments, but nixpacks appear to result in Docker enviroments so I don't think this has to be considered as a special case), so they are assuaged by either (1) using your provided images that will set a fixed version of Node, or (2) a general Docker+Node environment would also use a fixed version of Node, which they are in control of from the start (e.g. FROM node:20).

[VxJasonxV]

Should this issue be reopened if you're considering doing further work on it?