Fixing Common Problems

The fix that solves most things: reinstall cleanly

If an install seems broken or a package acts strangely, the single most effective fix is to delete the generated files and rebuild them from your package.json and lockfile. Remember: node_modules is disposable — the two small files are the source of truth.

The classic clean reinstall

Terminal 
$ rm -rf node_modules package-lock.json   # Mac/Linux
$ npm install
In VS Code
  1. In VS Code's file explorer you can delete the node_modules folder and package-lock.json by hand
  2. Then run npm install in the terminal to rebuild them from scratch
  3. On Windows PowerShell, delete with: Remove-Item -Recurse -Force node_modules, package-lock.json

This clears out corrupted or half-installed packages. It's safe: everything is rebuilt from package.json. It's the first thing to try for mysterious errors.

Clearing the npm cache

npm keeps a cache of downloaded packages to speed things up. Very occasionally that cache gets corrupted and causes odd download errors. Clearing it forces fresh downloads:

Clear the download cache

Terminal 
$ npm cache clean --force
$ npm install
In VS Code
  1. Run in the integrated terminal
  2. Follow it with a clean reinstall (above) so packages are fetched fresh

You rarely need this, but it's the next thing to try if a clean reinstall alone didn't fix a download/integrity error.

"Unsupported engine" — wrong Node version

If you see a warning about an unsupported engine, a package needs a different Node version than you have. Check what the project asks for (its engines field) against what you're running:

Check and switch Node version

Terminal 
$ node -v                 # what you have
$ # this project's package.json wants:  >=22.12.0
$ nvm install 22          # with the nvm version manager
$ nvm use 22
In VS Code
  1. Compare node -v with the project's engines requirement
  2. Install a matching Node version — a manager like nvm makes switching painless
  3. Reopen the VS Code terminal so it picks up the new version

Mismatched Node versions are a top cause of installs that work on one machine but not another. Matching engines fixes it.

Permission errors (EACCES) — don't reach for sudo

Seeing EACCES or "permission denied", usually during a global install? The instinct is to retype the command with sudo — resist it. sudo tends to create files your normal user can't manage later, making the problem worse over time.

  • Best fix: use a version manager like nvm, which puts Node and global packages in your home folder where you already have permission.
  • Often unnecessary anyway: most things don't need a global install — a local npm install inside the project rarely hits permission issues at all.

"Cannot find module 'x'"

This common error means Node went looking for a package and didn't find it. Two usual causes:

  • It isn't installed. Run npm install (to get everything) or npm install x (to add that specific one). Also check the name is spelled exactly right.
  • The dev server is stale. If you installed something while npm run dev was already running, stop it (Ctrl+C) and start it again so it sees the new package.

Resolve a missing module

Terminal 
$ npm install            # install everything package.json lists
$ # still missing one specific package?
$ npm install the-package-name
In VS Code
  1. Run the install in the terminal
  2. Restart the dev server: stop it with Ctrl+C, then npm run dev again

If you just cloned a project and nothing works, the answer is almost always a plain 'npm install' you skipped.

One more, for teams: a Git merge conflict in package-lock.json looks scary but is routine — don't edit it by hand. Accept either side, then run npm install to let npm regenerate a correct lockfile, and commit that.

Up next: the cheat sheet — every command from this guide on one page, with its VS Code equivalent.

FAQ

Frequently Asked Questions

My install is broken — what is the universal fix?
Delete the node_modules folder and package-lock.json, then run npm install again to rebuild them cleanly. This clears most corrupted-install problems.
I get an "Unsupported engine" or Node version error. What now?
A package needs a different Node version than you have. Install the version named in package.json's engines field — a manager like nvm lets you switch Node versions per project.
Should I use sudo to fix npm permission errors?
Avoid sudo — it usually makes permissions worse. Instead use a version manager (nvm) or fix your global folder's ownership. Local project installs rarely need elevated permissions at all.
Why does it say "Cannot find module"?
Either the package isn't installed (run npm install, or npm install <pkg>) or your dev server is still running with the old state — stop it and start it again so it picks up the new package.