Tag Archives: NodeJS version mismatch

NodeJS version does not meet requirements – Gulp serve error

Posted on by
Reply

NodeJS version does not meet requirements error while running gulp serve command. If gulp serve just failed with a Node version warning, you’re not alone. SPFx toolchains only support specific Node.js ranges. If your machine is on a newer major release (e.g., v22.x), the build refuses to run. Good news: you don’t need to reinstall everything—just switch to a supported Node version, reinstall dependencies, and rebuild. The exact gulp serve error as below :

Advertisements 
PS C:\SPFX\gulp serve
Error: Your dev environment is running NodeJS version v22.19.0 which does not meet the requirements for running this tool. This tool requires a version of NodeJS that matches >=12.13.0 <13.0.0 || >=14.15.0 <15.0.0 || >=16.13.0 <17.0.0 || >=18.17.1 <19.0.0 || >=20.11.0 <21.0.0
    at SPWebBuildRig.initialize (C:\SPFX\node_modules\@microsoft\sp-build-web\lib\SPBuildRig.js:50:19)
    at Object.initialize (C:\SPFX\node_modules\@microsoft\sp-build-web\lib\index.js:35:17)
    at Object.<anonymous> (C:\SPFX\gulpfile.js:16:7)
    at Module._compile (node:internal/modules/cjs/loader:1706:14)
    at Object..js (node:internal/modules/cjs/loader:1839:10)
    at Module.load (node:internal/modules/cjs/loader:1441:32)
    at Function._load (node:internal/modules/cjs/loader:1263:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:237:24)
    at Module.require (node:internal/modules/cjs/loader:1463:12)
Advertisements

Why this happens

Your Node.js version (v22.19.0 in this case) is outside the ranges the SPFx tooling supports. The guard prevents cryptic build failures later in the process.

Install and switch NodeJ version

Follow the command below to install specific nodejs version.

nvm install 20.19.5
nvm use 20.19.5
Advertisements

Clean and reinstall SPFX dependencies

Follow the command below to clean spfx dependencies and reinstall spfx dependencies.

Remove-Item -LiteralPath .\node_modules -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath .\package-lock.json -Force -ErrorAction SilentlyContinue
npm cache clean --force
npm install
Advertisements

Rebuild and run gulp serve

Follow the below commands to clean, build, trust certificate and serve again.

gulp clean
gulp build
gulp trust-dev-cert
gulp serve

Now the issue NodeJS version does not meet requirements should be resolved.

Advertisements
Which Node versions are acceptable for this SPFx toolchain ?

From the error message, any of:
=12.13.0 <13.0.0 · >=14.15.0 <15.0.0 · >=16.13.0 <17.0.0 · >=18.17.1 <19.0.0 · >=20.11.0 <21.0.0.

Why not use Node 22.x ?

SPFx tooling typically lags the latest Node majors. A newer runtime can break gulp tasks and native dependency builds.

Do I need to reinstall global CLIs after switching Node ?

Often yes—each Node version has its own global tool set (npm i -g ).

Can winget fix this by itself ?

winget can install a specific Node, but nvm/nvm-windows is the best way to switch versions per project.