Node.js Module Resolution: Why 'Cannot Find Module' Keeps Happening

When Node.js encounters a `require('some-module')`, it follows a deterministic algorithm: first, it checks if 'some-module' is a core module (like 'fs' or 'path'). If not, it looks for a file or directory named 'some-module' in the current directory's `node_modules`. If not found, it moves to the parent directory's `node_modules`, and so on, all the way up to the root. If still not found, it checks global install paths (like `/usr/local/lib/node_modules`). Finally, it throws the 'Cannot find module' error.

The key detail often missed: Node.js will resolve a package.jsons `main` field, but also the `exports` field if present (since Node 12). If `exports` is defined, it restricts what can be imported from the package. For example, a package with `"exports": { "./utils": "./dist/utils.js" }` will allow `require('pkg/utils')` but deny `require('pkg/subdir/secret.js')`. Many developers hit this when they try to import a file that isn't listed in `exports`. The fix is either to add the subpath to `exports` or import the default entry point.

Another nuance: Node.js caches resolved modules in `require.cache`. If you have a broken symlink that was resolved once (maybe to a different path), subsequent requires will use the cached result. Deleting the cache or restarting the process is necessary. Also, `require.resolve()` does not load the module — it only resolves the path, which is useful for debugging without side effects.

In monorepo setups (npm workspaces, Yarn workspaces, pnpm), dependencies are installed in a root `node_modules` and symlinked from workspace packages. A common failure is when a workspace package's `node_modules/.bin` contains a symlink to a binary that doesn't exist, or when a dependency's symlink points to a different version than expected. This often manifests as 'Cannot find module' for a transitive dependency that exists somewhere in the tree but not in the exact location Node is searching.

To diagnose symlink issues, use `ls -la node_modules/@scope/pkg` to see the symlink target. Then `readlink -f` to get the absolute path. Verify that path exists. For hoisting issues, check if the module is installed at multiple levels: `npm ls --all | grep module-name`. If you see two different versions, Node might pick the wrong one depending on the require path. The fix is often to align versions across workspaces using a `resolutions` field in package.json or `npm dedupe`.

pnpm users have a different beast: pnpm uses hard links and a content-addressable store. 'Cannot find module' errors there often stem from a missing `--shamefully-hoist` flag or from a package that expects to find its dependencies in the root `node_modules` but pnpm hasn't hoisted them. Check if the module is in `.pnpm` store and if the symlink to the store is correct.

The classic 'works on my machine' bug. Windows filesystems (NTFS) are case-insensitive by default, so `require('./MyModule')` and `require('./mymodule')` both find the same file. Linux (ext4, XFS) and macOS (APFS, case-sensitive by default since macOS 10.13) treat them as different files. If you develop on Windows and deploy to Linux, an accidental case mismatch will trigger 'Cannot find module'.

To catch this early, configure ESLint with `import/no-unresolved` rule and set it to case-sensitive. Also, run `find . -name '*.js' -exec sh -c 'echo {} | grep -E [A-Z]' \;` to list all files with uppercase characters — they might be the culprit. The fix is to rename the file to match the import case. A good practice is to enforce lowercase file names in your project (except for React components, which conventionally use PascalCase).

Note that npm itself on Linux will fail to install a package if the tarball contains files with the same name but different case. This can lead to incomplete installations and 'Cannot find module' errors for specific files.

Modules that contain native code (like `node-canvas`, `sharp`, `sqlite3`) rely on `node-gyp` to compile during installation. If the build environment lacks necessary tools (Python, C++ compiler, make), the postinstall script fails silently (or with a warning), leaving behind an incomplete module that has a package.json but no compiled `.node` file. When you require the module, Node.js tries to load the native addon and fails with 'Cannot find module' or 'Module did not self-register'.

Check if a native module is the culprit by looking at the error stack trace: if it mentions `.node` or `Module._load`, it's likely a native addon. Run `npm rebuild` to recompile all native modules. If that fails, install build tools: on Ubuntu, `sudo apt install build-essential python3`; on macOS, `xcode-select --install`. For Docker, ensure the base image includes these tools. Also, consider using `prebuild-install` or prebuilt binaries to avoid compilation entirely.

Another scenario: a native module requires a specific platform (e.g., `darwin` vs `linux`). If you npm install on macOS and then copy node_modules to a Linux container, the .node files won't match the architecture. Always run `npm ci` or `npm install` in the target environment to ensure native addons are compiled for the correct platform.

Since Node.js 12.7.0, packages can define an `exports` field to control which subpaths are publicly accessible. This is a double-edged sword: it improves encapsulation but can also cause 'Cannot find module' when you try to import a subpath that the package author didn't expose. For example, importing from `lodash/array` works because lodash's package.json has `"exports": { "./array": "./array.js" }`. But if you try `lodash/internal/private.js`, you'll get an error even though the file exists on disk.

To debug, first check the module's package.json: look for `exports`. If it exists, only the listed subpaths are importable. If the subpath you need is missing, either import the default entry or ask the package maintainer to add the subpath. For your own packages, be deliberate about what you expose. A common mistake is to have `exports` defined but not list all the files you intend to be public, causing internal imports to fail in consuming projects.

Also note that `exports` can be conditional, e.g., `{ "import": "./dist/index.mjs", "require": "./dist/index.cjs" }`. If you use CommonJS and the package doesn't have a `require` condition, Node.js will fail to resolve it. Always test both ESM and CommonJS entry points if your package supports both.