Quick answer
The error "Node.js version not compatible" usually means your project requires a different Node.js version than the one installed. The solution is to check the current version, install the appropriate one (e.g. via nvm on macOS/Linux or nvm-windows on Windows) and reinstall dependencies.
How to recognize the problem
- npm install or yarn install reports an incompatible Node.js version error
- The application does not start or crashes immediately after starting
- The message contains "engine" or "Unsupported engine" and the required version
- Some features work, but the build or tests fail
- CI/CD pipeline reports an error due to Node.js version
Most common causes
Project requires a newer Node.js version
The package.json or .nvmrc file specifies a minimum version that the current installation does not meet.
Outdated Node.js version installed
The system has an older version (e.g. 22.x) while the project requires 24.x or a newer LTS version.
Multiple Node.js versions conflict
There are multiple installations on the computer, and PATH points to the wrong one or global npm is used instead of local.
Missing version management
Without a tool like nvm, switching between projects requires manual installation and uninstallation.
Step-by-step fix
- 1
Check the current Node.js version
Open a terminal and run
node -vandnpm -v. Note the output. Also check if the project has a.nvmrcfile or anenginesfield inpackage.jsonthat defines the required version. - 2
Find the required version
If the project has a
.nvmrc, the content of that file is the version to use. Otherwise, check theenginesfield inpackage.jsonor the project documentation. If there is no information, install the current LTS version from the official nodejs.org website. - 3
Install a version management tool (recommended)
On Windows, download and install nvm-windows from the official GitHub repository. On macOS/Linux, use
nvm(Node Version Manager) according to the instructions on the official website. Close and reopen the terminal after installation. - 4
Install the appropriate Node.js version
If using nvm, run
nvm install 24(replace the number with the version the project requires). Then activate it withnvm use 24. On Windows with nvm-windows, the commands are the same, but run them in Command Prompt or PowerShell. - 5
Set the default version (optional)
To avoid reactivating, on macOS/Linux set the default version:
nvm alias default 24. On Windows with nvm-windows, just runnvm use 24; nvm-windows does not supportalias default. Check withnode -vthat the correct version is active. - 6
Clear cache and reinstall dependencies
Make a backup or check that changes are saved in Git. Delete
node_modules, andpackage-lock.json(oryarn.lock) only if necessary. Then if needed runnpm cache clean --forceandnpm install(oryarn install/pnpm install, depending on the package manager). This avoids remnants of old binary modules that can cause errors. - 7
Check if the error persists
Run
npm run buildornpm startand check the output. If you still get a version error, check if a global package requires a different version or if PATH is correct (which nodeon macOS/Linux,where.exe nodeon Windows). - 8
Update CI/CD configuration
If you use GitHub Actions, GitLab CI or similar, set the same Node.js version in the configuration file (e.g.
node-version: 24). Do not forget to align your local environment with the CI environment.
If nothing helps
If you have tried all steps and the error remains, check if the project has an .npmrc with engine-strict=true that blocks installation. You can temporarily remove it or set it to false, but do this only if you understand the consequences. Also, check if you are using the appropriate package manager (npm, yarn, pnpm) and its version. Sometimes you need to clear the global npm cache and reinstall npm. If the error occurs only on the production server, check if the same Node.js version is installed there as locally. For complex projects with multiple microservices, consider using Docker which guarantees a consistent environment.
How to prevent it
- Always use `.nvmrc` or `engines` in `package.json` to explicitly specify the Node.js version.
- Regularly update Node.js to a stable LTS version and monitor when projects require a newer one.
- Use a version management tool (nvm, nvm-windows, fnm) for easy switching between projects.
- In the CI/CD pipeline, define the same Node.js version as in local development.
When to call a professional
If the error affects the production environment or you cannot align versions within the team, contact IT support. They can set up the correct environment and prevent work stoppages.
Software and product development · Custom apps, SaaS and an MVP in 4 to 8 weeksFAQ
How do I know which Node.js version the project requires?
It is usually written in `.nvmrc` or in the `engines` field inside `package.json`. If that information is missing, check the README or project documentation. Otherwise, install the latest LTS version.
Can I install multiple Node.js versions at the same time?
Yes, use nvm (macOS/Linux) or nvm-windows. They allow you to install multiple versions and choose which one to use per project.
Is it safe to delete node_modules and package-lock.json?
Deleting `node_modules` is common and safe if you then reinstall dependencies. Deleting `package-lock.json` or `yarn.lock` can change the dependency tree, so do it only if necessary and first save the file or check that the change is committed. After deletion, run `npm install` (or the appropriate command for yarn/pnpm).