Next.js refuses to run on an old Node.js version
Next.js App Requires Node.js Version >= v18.17.0, but Encountering Error with Node.js 16.20.2Short answer
Each Next.js release sets a minimum Node.js version. Next.js 16 needs 20.9 or newer and no longer supports Node.js 18. Check node -v, install a current LTS with nvm, and set it as the default so new terminals use it. A .nvmrc in the repository keeps the whole team on the same version.
Fix it fast
1Find out which cause you have
Compare the Node.js version this shell runs against the minimum for your Next.js version.
node -v npx next --version2Match what you see, then jump to its fix
- 1
node -v prints a version below the requirementThe installed Node.js is older than the minimumFix - 2
It works in one terminal and the old version returns in a new onenvm use only changed the current terminalFix - 3
nvm use switches to an old version inside the project folderA .nvmrc pins the project to an old versionFix
- 1
What does the error look like?
Next.js App Requires Node.js Version >= v18.17.0, but Encountering Error with Node.js 16.20.2
Cause 1 of 3
The installed Node.js is older than the minimum
1Check
Next.js 16 sets a minimum of Node.js 20.9.0 (LTS) and drops Node.js 18. The installation page lists the same minimum.
node -v2Fix
Install the latest LTS release with nvm and switch to it.
nvm install --lts
nvm use --lts3Verify
node -v shows the new version and the dev server starts.
node -v
npm run devConfirmed by nextjs.org
Cause 2 of 3
nvm use only changed the current terminal
1Check
New shells start with the nvm default alias, not with what nvm use selected earlier.
nvm alias default2Fix
Set the default alias to the version you want.
nvm alias default 'lts/*'3Verify
Open a new terminal and check.
node -vConfirmed by github.com
Cause 3 of 3
A .nvmrc pins the project to an old version
1Check
nvm use and nvm install read the version from .nvmrc when no version is given on the command line.
cat .nvmrc2Fix
Write a supported version into the file and reinstall.
echo "lts/*" > .nvmrc
nvm install3Verify
Run nvm use in the project and confirm the version.
nvm use
node -vConfirmed by github.com
How do I stop it coming back?
- Read the Node.js minimum in the upgrade guide before every Next.js major upgrade.
- Commit a .nvmrc so teammates use the same version.
- Set the Node.js version in your CI and hosting settings to match.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix