Cannot find module 'X' error in Node.js [Solved]

avatar
Borislav Hadzhiev

Last updated: Jan 14, 2023
5 min

banner

# Cannot find module 'X' error in Node.js

The "Cannot find module" error in Node.js occurs for multiple reasons:

  1. Forgetting to install a third-party package with npm install module-name.
  2. Pointing the node command to a file that doesn't exist.
  3. Having an outdated version of the package, or an IDE or development server glitch.
  4. Forgetting to install type definitions for a package in a TypeScript project.

cannot find module

To solve the "Cannot find module" error in Node.js, make sure to install the package from the error message if it's a third-party package, e.g. npm install module-name.

If you get the error with a local module, make sure to point the node command to a file that exists.

If your error message contains a third-party package name, e.g. "Cannot find module 'uuid'", then you have to install the uuid package.

Open your terminal in your project's root directory (where your package.json file is located) and run the following commands.

shell
# ๐Ÿ‘‡๏ธ if you use NPM npm install uuid # ๐Ÿ‘‡๏ธ only if you use TypeScript npm install --save-dev @types/uuid # ---------------------------------------- # ๐Ÿ‘‡๏ธ if you use YARN yarn add uuid # ๐Ÿ‘‡๏ธ only if you use TypeScript yarn add @types/uuid --dev

npm install module

This will add the third-party package to the dependencies of your project and you will be able to import it.

# Remove your node_modules and reinstall your dependencies

If the error is not resolved, try to delete your node_modules and package-lock.json (not package.json) files, re-run npm install and restart your IDE.

shell
# ๐Ÿ‘‡๏ธ Windows - delete node_modules and package-lock.json rd /s /q "node_modules" del package-lock.json # ๐Ÿ‘‡๏ธ macOS/Linux - delete node_modules and package-lock.json rm -rf node_modules rm -f package-lock.json # ๐Ÿ‘‡๏ธ clean npm cache npm cache clean --force # ๐Ÿ‘‡๏ธ install packages npm install
Make sure to restart your IDE and dev server if the error persists. VSCode often glitches and needs a reboot.

# Cannot find module 'X' when running local files in Node.js

If you are getting the "Cannot find module" error when trying to run a local file, make sure that the path you passed to the node command points to a file that exists.

For example, if you run node src/index.js, make sure that the path src/index.js points to an existing file.

run local file node js

If you get the error because a local file is not found, try to use the Tab key after the node command to autocomplete the path to the module you are trying to run.

If you don't get autocompletion when starting to type the path to the module, chances are the path is incorrect.

The path pointing to the module you're trying to run is relative to the directory in which you opened your terminal.

You can try to open your terminal in the directory that contains the file you're trying to run and directly pass it to the node command, e.g. node index.js.

# Cannot find module 'X' when using global packages

If you need to install a package globally to be able to run it on the command line from every directory, use the -g flag.

shell
npm install -g some-package # ๐Ÿ‘‡๏ธ this links globally installed package to local node_modules folder npm link some-package

npm install package globally

If the global installation of the package fails, you might have to run the command prefixed with sudo (macOS and Linux) or start Command Prompt as an Administrator (Windows).
shell
# ๐Ÿ‘‡๏ธ If you got permissions error, run with sudo sudo npm install -g some-package npm link some-package

The npm link command creates a symbolic link from the globally installed package to the node_modules/ directory of the current folder.

You can also use the npx command to avoid having to install the package globally.

shell
npx create-react-app --version

using npx command prefix

You simply have to prefix the command with npx.

# Cannot find module 'X' when using TypeScript

If you got the error in a TypeScript project, install the type definitions for the package by running npm install -D @types/some-package and ensure the types array in your tsconfig.json file contains the string node.

tsconfig.json
{ "compilerOptions": { "types": [ "node" ] }, }

For example, this command installs the type definitions for the uuid package.

shell
npm install -D @types/uuid

npm install type definitions

This should fix the error and now TypeScript should be able to find the type definitions for the specific module.

If you still get the "Cannot find module" error in your Node.js project, open your package.json file and make sure it contains the name of the package in the dependencies object.

package.json
{ // ... rest "dependencies": { "some-module": "^2.8.5", }, }

You can try to manually add the line and re-run npm install.

shell
npm install

Or install the latest version of the package:

shell
npm install some-module@latest

If the error is still not resolved, open your terminal and check if you have Node.js installed by running the following command:

shell
node -v

get node js version

If you get a version number back, you have Node.js installed, otherwise install it by visiting the official Node.js downloads page.

Make sure the path to your project does not contain a hash # symbol or any other special characters that your operating system might have issues resolving. For example, don't use a path like my-folder#3/my-project/my-file.js (contains a hash #).

Special characters in your directory path might cause the "Cannot find module" error.

If you got the error when connected to a Linux server, try to exit from the server and SSH back into it.

If the error occurred after running the brew install yarn command on macOS, try issuing the following command.

shell
# ๐Ÿ‘‡๏ธ use global directory to store packages yarn global add npm

# NPM might be installing packages in a location that is not in your PATH

If none of the suggestions helped, the issue might be that npm is installing packages in a location that is not in your PATH environment variable.

The easiest way to resolve the error, in this case, would be to uninstall Node.js and reinstall it using the official Node.js downloads page.

If you get prompted whether you want to add Node.js and npm to your PATH environment variable during the installation, make sure to tick the option.

# Conclusion

To solve the "Cannot find module" error in Node.js, make sure to install the package from the error message if it's a third-party package, e.g. npm i module-name.

If you get the error with a local module, make sure to point the node command to a file that exists.

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.
book cover
You can use the search field on my Home Page to filter through all of my articles.

Copyright ยฉ 2024 Borislav Hadzhiev