Cannot find module error in Node.js (Fixed)

“Error: cannot find module” occurs when you try to load a non-existant module in Node – Either via ESM (ECMAScript Modules) or CommonJS module systems. 

🎧 Debugging Jam

Calling all coders in need of a rhythm boost! Tune in to our 24/7 Lofi Coding Radio on YouTube, and let's code to the beat – subscribe for the ultimate coding groove!" Let the bug-hunting begin! 🎵💻🚀

The error usually looks like this in the console:

node:internal/modules/cjs/loader:936
  throw err;
  ^

Error: Cannot find module '/var/www/scripts/app.js'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:17:47 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Psssst! Do you want to learn web development in 2023?

It's not too late! Read these first:

• How to become a web developer when you have no degree
• How to learn to code without a technical background
• How much do web developers make in the US?

Why does "Error: cannot find module" occur?

The error "cannot find module" might happen if you're trying to:

• Import a third-party package you haven't installed yet (with npm or yarn).
• Import a local module, but the path is wrong.
•  Run a node script in the terminal, but the script doesn't exist (or path is wrong).
• Use node standard libraries with TypeScript, but you haven't installed the @types/node package.
• The module's package.json has a main field pointing to an entry file that doesn't exist.

Before anything, let's review what a module is and how module systems work in a high level (see the solutions).

The module system: Modules are the building blocks of an application. Node implements ESM and CommonJS (the default one) module systems to let you organize your code as reusable components. 

With modules, you can only expose the public interface of your components and keep the internal functionalities private. This is done by using a module.exports (CommonJS modules) or export (ES Modules). 

The following code is an example of a module, which has a function to determine whether a number is odd or not:

function isOdd(number) {
return number % 2 !== 0
}

// Make isOdd available to other scripts (and other modules)
module.exports = isOdd

And here's how we import it into another script called index.js:

// index.js 
const add = require('./isodd.js') 

console.log(isOdd(3)) 
// output: true

All the modules you use have an ESM or CommonJS export declaration.

How do module systems find modules?

If the identifier passed to require() or import() is a reference to a file (it starts with /, ../, ./, etc.) in your filesystem, Node will load it from the respective path. Otherwise, it looks it up in the installed modules - inside the node_modules directory.

If the module isn't found, it raises the "Cannot find module" error.

How to fix the "Cannot find module" error in Node.js?

There are several scenarios this error can happen; Let's explore each.

Third-party packages: If you try to import a third-party module and get this error (and you're sure the spelling is correct), you probably haven't installed the package yet.

Imagine this is the code:

const axios = require('axios');

// Make an HTTP request with Axios

If I run this on my machine, I'll get the "Cannot find module" error.

And that's because I haven't installed it yet. So in my project directory (where my package.json resides), I'd have to install axios package with npm or yarn like so:

npm install axios

2. Local modules: Imagine you have a set of utility functions kept in a JavaScript file named utils.js. You want to import a function called getUrl() from this utils.js into your script:

const { getUrl } = require('utils')

// Do something here ...

But when you run npm run build, the build fails:

ERROR in ./app/index.js 30:0-30
Module not found: Error: Can't resolve 'utils' in '/var/www/app'

In this case, since utils isn't a reference to a local file, my bundler (Webpack) assumes it's inside a node_modules directory. The build fails as the utils module isn't an installed package.

So what I need to do here is to make it an absolute path by adding ./ to my identifier:

const { getUrl } = require('./utils.js')

// Do something here ...

Problem solved.

Sometimes the error occurs because the letter casing is off. File names on Mac and Windows are case-insensitive by default; This means ./Utils and ./utils both work on Mac and Windows (where you develop the app). However, it'll break on a Linux file system where filenames are case-sensitive.

3. Running a node script: Another scenario reported by developers is when you run a script with the node command. However, the respective file can't be located - probably owing to a typo in the name or path.

So always double-check that the path is correct and the script exists. You can always take advantage of the terminal's autocomplete feature by typing the initial letters and pressing the tab to let it complete the path for you.

node ./scriptName.js

4. Node and TypeScript: If you're coding in TypeScript and you're importing a built-in Node module like fs, you might get a "Cannot find module 'fs'" error too.

You can fix the issue by installing @types/node:

npm install @types/node --save-dev

Even though all packages in node_modules/@types (of any enclosing folder) are included in your compilation. However, it's worth ensuring node is added under compileOptions.types:

{
  compilerOptions: {
    types: [node, jest, express]
  }
}

5. Missing entry file in package.json: Each module has an entry file, which is index.js by default - unless it's changed in the module's package.json via the main field.

{
  name: utils
}

If you decide to change the main field to another entry file (e.g., main.js), you must ensure the file exists. Or if you rename or relocate that file in the future, remember to update the package.json too.

Missing entry file in package.json has been reported by several users on Stackoverflow.

6. Importing a module from the global node_modules or a separate directory: Sometimes you might have to use a globally-installed package in your development environment.

If you try to load a globally-installed module in your project, you might get the "Cannot find module" error.

A workaround to this problem is using the npm link command. If the package is installed globally, all you need to do is run the following command while in your project directory:

npm link package-name

As a result, npm will create a symbolic link from the globally installed package name to the node_modules directory of your project - as if you've installed it with npm install package-name.

If the module you want to use is a local file residing somewhere in your file system other than the global node_modules (e.g., a module you're developing), you'll have to do it as a two-step process:

First step: In the terminal, you need to change the directory to where the module resides and run the npm link (without any parameter). As a result, a symlink is created in the global node_modules that links to your local package.

npm link

Second step: After that, you change the directory to your project directory (where you want to import the module) and run the following command:

npm link package-name

This will create a symbolic link from the globally installed package name to the node_modules directory of your project.

Now, you can use the package as if it's an installed third-party package.

What if the problem persists?

If none of the above solutions worked for you, maybe you're dealing with corrupted or incomplete installations. In that case, you can take the following steps:

1. Delete node_module directory:

rm -rf node_modules

2. Delete package-lock.json:

rm -f package-lock.json

3. Clear the npm cache:

npm cache clean --force

4. Install the packages again:

npm install

This will make a clean install of all the dependencies listed in your package.json file.

Wrapping up

I hope these solutions help you fix your code.

Thanks for reading.

Reza Lavarian Hey 👋 I'm a software engineer, an author, and an open-source contributor. I enjoy helping people (including myself) decode the complex side of technology. I share my findings on Twitter: @rezalavarian