How to fix Error: Node.js version 10.x is required, but 8.x is running in Node.js

Node.jsBEGINNERHIGHUpdated Dec 9, 2025· 161 views

This error occurs when an application or package requires a specific Node.js version, but a different version is currently running. Common in projects with strict version requirements or when switching between projects with different Node.js dependencies.

Quick fix

Fixes Error: Node.js version 10.x is required, but 8.x is running

node --version
# or
node -v
  1. Check current and required Node.js versions
  2. Install and use Node Version Manager (nvm)
  3. Create .nvmrc file for automatic version switching
  4. Rebuild native modules after version change
node.js — error
node --version
# or
node -v
Error: Node.js version 10.x is required, but 8.x is running

What this error means

This error indicates that the Node.js runtime version currently executing your code does not match the version requirement specified by your application, package, or dependency. Node.js applications often define version constraints in their package.json file using the "engines" field, or dependencies may have been compiled against a specific Node.js version using native modules. When you see this error, it means the package manager, build tool, or application itself has detected an incompatibility between what's installed on your system and what's needed to run properly. This commonly happens when working across multiple projects with different Node.js requirements, after system upgrades, or in CI/CD environments where the runtime version differs from the development environment. Version mismatches can cause runtime errors, failed builds, or incorrect behavior because different Node.js versions may have different APIs, language features, or compiled native module interfaces (NODE_MODULE_VERSION).

Typical symptoms

  • Application fails to start with version requirement error message
  • npm install or npm start commands fail with version warnings
  • Package manager shows engine compatibility warnings
  • Native modules fail to load with MODULE_VERSION mismatch errors
  • CI/CD pipelines fail at the Node.js version check step
  • Different behavior between local development and production environments
  • Build processes fail with "unsupported Node.js version" messages

Common causes

  1. Running node command that points to an older or newer Node.js installation than required
  2. package.json engines field specifies a Node.js version range that excludes the current version
  3. Native dependencies compiled against a different NODE_MODULE_VERSION
  4. Using system-installed Node.js instead of project-specific version managed by nvm or similar tools
  5. CI/CD environment configured with wrong Node.js version
  6. Switching between projects without changing Node.js versions
  7. Node.js upgraded or downgraded system-wide without rebuilding project dependencies
  8. Dockerfile or deployment configuration specifying incompatible Node.js version

How to fix "Error: Node.js version 10.x is required, but 8.x is running"

1Check current and required Node.js versions

First, identify the version mismatch by checking what's running versus what's required.

Check your current Node.js version:

bash
node --version
# or
node -v

Check what version your project requires in package.json:

bash
cat package.json | grep -A 2 "engines"

You should see output like:

json
"engines": {
  "node": ">=10.0.0"
}

Compare these versions to understand the gap.

2Install and use Node Version Manager (nvm)

The most reliable way to manage multiple Node.js versions is using nvm (Node Version Manager).

Install nvm (Linux/macOS):

bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Restart your terminal after installation

For Windows, use nvm-windows:

bash
# Download and install from: https://github.com/coreybutler/nvm-windows/releases

Install the required Node.js version:

bash
nvm install 10.24.1  # Replace with your required version

Switch to the required version:

bash
nvm use 10.24.1

Verify the change:

bash
node --version
3Create .nvmrc file for automatic version switching

To avoid manually switching versions, create an .nvmrc file in your project root.

Create .nvmrc with the required version:

bash
echo "10.24.1" > .nvmrc

Or if you want to match package.json engines field:

bash
node -p "require('./package.json').engines.node" > .nvmrc

Now when you enter the project directory, run:

bash
nvm use

This will automatically switch to the version specified in .nvmrc.

For automatic switching, add this to your ~/.bashrc or ~/.zshrc:

bash
# Auto-switch Node version with .nvmrc
autoload -U add-zsh-hook
load-nvmrc() {
  if [[ -f .nvmrc && -r .nvmrc ]]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc
4Rebuild native modules after version change

If you've switched Node.js versions, native modules need to be rebuilt.

Delete node_modules and package-lock.json:

bash
rm -rf node_modules package-lock.json

Clear npm cache:

bash
npm cache clean --force

Reinstall dependencies:

bash
npm install

If you only need to rebuild native modules without full reinstall:

bash
npm rebuild

For specific packages with native bindings:

bash
npm rebuild node-sass
npm rebuild bcrypt
# etc.
5Update package.json engines field (if appropriate)

If you need to update version requirements to match your environment, modify package.json.

Update the engines field:

json
{
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  }
}

To enforce strict version checking, enable engine-strict:

bash
npm config set engine-strict true

Or create/update .npmrc in project root:

bash
engine-strict=true

This will prevent npm from installing dependencies if the Node.js version doesn't match.

Note: Only update version requirements if you've tested compatibility. Don't arbitrarily change requirements just to bypass the error.

6Fix CI/CD and deployment environments

Ensure your CI/CD pipeline and deployment environments use the correct Node.js version.

For GitHub Actions (.github/workflows/ci.yml):

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '10.x'  # Match your requirements

For Docker (Dockerfile):

dockerfile
FROM node:10.24.1-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
CMD ["node", "index.js"]

For Heroku, create/update buildpack:

json
{
  "engines": {
    "node": "10.x"
  }
}

For Azure App Service, set WEBSITE_NODE_DEFAULT_VERSION:

bash
az webapp config appsettings set --name <app-name> --resource-group <group-name> --settings WEBSITE_NODE_DEFAULT_VERSION="~10"

Advanced notes

Version Range Syntax: The engines field supports semantic versioning ranges: ">=10.0.0 <11.0.0" (between versions), "^10.0.0" (compatible with 10.x), "~10.5.0" (allow patch updates only), or "10.x" (any 10.x version). Understanding these ranges helps you balance compatibility with feature requirements.

Alternative Version Managers: Besides nvm, consider "n" (npm install -g n), "fnm" (Fast Node Manager, written in Rust), or "volta" (cross-platform tool that also manages npm and yarn versions). Volta is particularly useful in team environments as it reads version info from package.json automatically.

NODE_MODULE_VERSION: Each Node.js version has an associated NODE_MODULE_VERSION that determines native module compatibility. When you see "was compiled against a different Node.js version," the module needs to be recompiled. You can check your version's MODULE_VERSION with: node -p "process.versions.modules".

Docker Multi-Stage Builds: Use multi-stage builds to ensure build and runtime Node.js versions match. Build stage can use a version with build tools, while runtime stage uses a minimal image with the exact required version.

LTS vs Current: Long Term Support (LTS) versions receive critical updates for 30 months, making them ideal for production. Current versions include latest features but have shorter support cycles. Check the Node.js release schedule at nodejs.org/en/about/releases/.

Team Synchronization: Use tools like "syncpack" to keep version requirements consistent across monorepos or microservices. Document the required Node.js version in README.md and consider adding a preinstall script that checks the version and exits with a clear error message if it doesn't match.

Frequently asked questions

What does "Error: Node.js version 10.x is required, but 8.x is running" mean?
js runtime version currently executing your code does not match the version requirement specified by your application, package, or dependency. js version using native modules. When you see this error, it means the package manager, build tool, or application itself has detected an incompatibility between what's installed on your system and what's needed to run properly.
How do I fix "Error: Node.js version 10.x is required, but 8.x is running"?
This error occurs when an application or package requires a specific Node.js version, but a different version is currently running. Common in projects with strict version requirements or when switching between projects with different Node.js dependencies.
What causes "Error: Node.js version 10.x is required, but 8.x is running"?
Running node command that points to an older or newer Node.js installation than required package.json engines field specifies a Node.js version range that excludes the current version Native dependencies compiled against a different NODE_MODULE_VERSION
Is the "Error: Node.js version 10.x is required, but 8.x is running" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading