fix(server): fail fast with a clear message on unsupported Node.js versions

[gaurav0107]

Summary

Running npx flowise start on an unsupported Node.js version crashes at startup with an opaque error:

ReferenceError: File is not defined
    at .../cheerio/node_modules/undici/lib/web/webidl/index.js:533:48

The File global only exists on Node.js >= 20, and undici (pulled in transitively via cheerio, used by the Cheerio document loader and the Web Scraper tool) references it at module-load time. Flowise declares engines.node: "^24", but that field is only advisory — npm install -g flowise succeeds on older runtimes and the user only finds out via the cryptic crash, with no hint that the real cause is their Node version. This matches the diagnosis in the issue thread ("are you on version 18+?").

This PR adds a small, dependency-free version guard that runs at the very top of bin/run, before @oclif/core loads any command (the start command imports the server — and therefore cheerio — at module scope, so the check has to happen first). When the running Node.js major is below the one declared in engines.node, it prints an actionable message and exits with code 1:

Flowise requires Node.js >= 24. You are running v18.20.0. Please upgrade Node.js
(https://nodejs.org) and try again. Running on an unsupported version causes startup
errors such as "ReferenceError: File is not defined".

Design notes:

• The required major is read from this package's own engines.node, so it stays in sync automatically.
• The comparison fails open: an unparseable running-version string is treated as supported, so an unexpected version format never blocks startup.
• The guard in bin/run is wrapped in try/catch, so the check can never itself break startup (e.g. when dist/ is not built in a dev tree).
• The logic lives in a pure, unit-tested helper (src/utils/nodeVersion.ts); bin/run only wires it in.

It does not attempt to make Flowise run on an unsupported Node.js version (not possible — undici needs the platform File global); it surfaces the real requirement instead of a stack trace.

Verification

• pnpm --filter flowise test — new suite src/utils/nodeVersion.test.ts passes (13/13): version parsing, engines range parsing, support comparison (including fail-open), the user-facing message, and assertNodeVersion.
• tsc (server) — clean, no new type errors introduced.
• eslint + prettier --check — clean on all changed files.
• Manual: requiring the compiled helper and calling assertNodeVersion('v18.0.0') returns the error message and process.exit(1) path; v24+ returns { ok: true }.

Scope is limited to packages/server (bin/run + one new helper + its test); no proprietary paths are touched.

Closes #5670

[gemini-code-assist]

Code Review

This pull request introduces a Node.js version check at startup to fail fast with a clear error message if the running Node.js version is unsupported (specifically to prevent opaque crashes on Node < 20 where the File global is missing). It adds utility functions for parsing and asserting the Node.js version along with corresponding unit tests. The review feedback suggests simplifying redundant string conversions in parseMajor, using loose equality (== null) for nullish checks in isSupportedNodeVersion, and removing unnecessary imports from @jest/globals in the test file to avoid potential dependency resolution issues.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

According to the repository's standard idioms, loose equality (== null) should be used for nullish checks to cover both null and undefined. Additionally, ensure that the check returns false if the node's version is missing to prevent synchronization UI elements from appearing for nodes that do not support versioning.

Suggested change

	if (major === null) return true
	if (major == null) return false

References

1. In JavaScript/TypeScript, use loose equality (== null) as a standard idiom for a 'nullish' check that covers both null and undefined.
2. When implementing version comparison for nodes, ensure that the check returns false if the node's version is missing. This prevents synchronization UI elements from appearing for nodes that do not support versioning, maintaining consistency with legacy implementations.

[gaurav0107]

Thanks for the review. I intentionally kept this returning true here (and used strict === null): parseMajor returns number | null (never undefined), and the goal is to fail open — when the running Node version string can't be parsed (nightly/custom builds), treat it as supported rather than block startup. Returning false would fail closed and could block legitimate users on unusual-but-valid runtimes. Note this is the Node.js process runtime version, not component/node versioning, so the legacy-versioning guidance doesn't apply.

[gemini-code-assist]

Since the version parameter is already typed as a string, the nullish coalescing and String() conversion are redundant. We can simplify this to directly trim the string.

Suggested change

	export const parseMajor = (version: string): number | null => {
	const match = /^v?(\d+)\./.exec(String(version ?? '').trim())
	return match ? parseInt(match[1], 10) : null
	}
	export const parseMajor = (version: string): number | null => {
	const match = /^v?(\\d+)\\./.exec(version.trim())
	return match ? parseInt(match[1], 10) : null
	}

[gaurav0107]

Good call — simplified to version.trim() in ec6e557. Thanks.

[gemini-code-assist]

Importing from @jest/globals is unnecessary because Jest globals (describe, expect, it) are already available globally and typed via @types/jest. Removing this import avoids potential phantom dependency resolution issues in strict package managers like pnpm.

[gaurav0107]

Done in ec6e557 — dropped the @jest/globals import to rely on Jest's global describe/expect/it (typed via @types/jest), matching the majority of the server test suite. Thanks.