This error occurs when Node.js attempts to import a directory but cannot locate an index.js file or a valid entry point specified in package.json. It typically happens when directory imports rely on implicit index file resolution.
This error indicates that Node.js's module resolution system attempted to load a directory as a module but failed to find the expected entry file. When you require or import a directory path in Node.js, the module system follows a specific resolution algorithm: it first checks for a package.json file with a "main" field pointing to an entry file, then falls back to looking for index.js, index.json, or index.node files in that directory. When none of these files exist or the "main" field points to a non-existent file, Node.js cannot determine how to load the module and throws this error. This is a fundamental part of Node.js's CommonJS module resolution system, which assumes directories being imported as modules must have a clear entry point. The error message typically includes the relative or absolute path to the directory that Node.js attempted to load, helping you identify which import statement is causing the problem.
First, check if the directory being imported actually contains an index.js file:
# Navigate to the directory being imported
ls -la ./path/to/directory
# Check if index.js exists
test -f ./path/to/directory/index.js && echo "File exists" || echo "File missing"If the file is missing, you need to either create it or update your import to point to the correct file.
If the directory should export a module but lacks an index.js file, create one:
// path/to/directory/index.js
// Export the main functionality from this directory
module.exports = require('./main-file');
// Or for ES modules:
export { default } from './main-file.js';
export * from './other-exports.js';This creates a proper entry point that Node.js can resolve when importing the directory.
If a package.json file exists in the directory, verify the "main" field:
{
"name": "my-module",
"main": "index.js",
"type": "commonjs"
}Ensure the path in "main" is relative to the package.json location and the file actually exists. Common mistakes:
// ❌ Wrong - absolute path
{ "main": "/src/index.js" }
// ❌ Wrong - file doesn't exist
{ "main": "dist/index.js" }
// ✅ Correct - relative path to existing file
{ "main": "./index.js" }Instead of importing directories, explicitly import the specific file:
// ❌ Directory import (requires index.js)
const myModule = require('./utils');
// ✅ Explicit file import
const myModule = require('./utils/helpers.js');
// For ES modules, always include the extension:
import myModule from './utils/helpers.js';This approach is more explicit and avoids relying on implicit index file resolution.
Check that file names match exactly, including case:
# Find files with case-insensitive search
find . -iname "index.js"
# This might reveal Index.js or INDEX.js instead of index.jsFix any casing mismatches:
# Rename to lowercase (Git-aware)
git mv Index.js index.jsRemember: macOS and Windows are case-insensitive by default, but Linux servers are case-sensitive.
If the missing module is in node_modules, reinstall dependencies:
# Remove existing installations
rm -rf node_modules package-lock.json
# Reinstall all dependencies
npm install
# Or with yarn
rm -rf node_modules yarn.lock
yarn installThis ensures all packages are properly installed with their correct directory structures.
Verify that index.js isn't being ignored by Git:
# Check if file is ignored
git check-ignore -v path/to/directory/index.js
# View what files are tracked
git ls-files path/to/directory/If the file is incorrectly ignored, update your .gitignore:
# Make sure you're not ignoring index files
# ❌ Too broad
*.js
# ✅ More specific
dist/**/*.js
build/**/*.jsThen track the file:
git add -f path/to/directory/index.js
git commit -m "Add missing index.js file"ES Modules vs CommonJS: When using ES modules (with "type": "module" in package.json), you must include file extensions in all import statements, even for index.js files. The implicit index file resolution still works, but you need to reference it as './directory/index.js' explicitly or use the directory path './directory' (which will resolve to index.js).
Exports Field Precedence: In modern Node.js packages, the "exports" field in package.json takes precedence over "main". If a package defines "exports" without including a mapping for the directory path you're importing, the import will fail even if index.js exists. Check the package's exports configuration:
{
"exports": {
".": "./index.js",
"./utils": "./src/utils/index.js"
}
}Circular Dependencies: Sometimes this error appears when refactoring code with circular dependencies. If module A imports directory B, which contains an index.js that imports module A, Node.js may fail to resolve the index.js file during the circular resolution. Use tools like madge to detect circular dependencies:
npx madge --circular --extensions js ./srcBundler Considerations: Build tools like webpack, Rollup, or esbuild have their own module resolution algorithms. If your code works in development but fails in production builds, check your bundler's configuration for directory import handling and ensure output paths match expected structures.
Monorepo and Workspace Issues: In monorepos using npm workspaces, Yarn workspaces, or pnpm, symlinked packages may have missing index.js files if workspace dependencies aren't properly linked. Run npm install or yarn install at the workspace root to ensure all internal dependencies are correctly symlinked.
Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams