Jest Cannot Find Module Error Fix

In this tutorial, you'll learn about Jest Cannot Find Module Error Fix. We cover key concepts, practical examples, and best practices.

You run jest and hit Cannot find module 'utils/helpers' — Jest doesn't resolve aliased paths the same way your bundler does, breaking imports that work fine at runtime.

The Problem

// WRONG — alias import that Jest cannot resolve
import { formatDate } from 'utils/helpers';

Cannot find module 'utils/helpers' from 'src/components/Header.js'

Jest uses Node's module resolution by default. Your bundler (Webpack, Vite) maps utils/helpers to src/utils/helpers.js via aliases, but Jest knows nothing about this mapping.

Step-by-Step Fix

1. Configure moduleNameMapper

// jest.config.js
module.exports = {
  moduleNameMapper: {
    '^utils/(.*)$': '<rootDir>/src/utils/$1',
    '^components/(.*)$': '<rootDir>/src/components/$1',
    '\\.(css|less|scss)$': '<rootDir>/__mocks__/styleMock.js',
    '\\.(png|jpg|svg)$': '<rootDir>/__mocks__/fileMock.js'
  }
};

Create the mock files:

// __mocks__/styleMock.js
module.exports = {};

// __mocks__/fileMock.js
module.exports = 'test-file-stub';

2. Fix import casing

// WRONG — case mismatch
import { User } from './models/User';

// RIGHT — matches actual filename
import { User } from './models/user';

File system is case-sensitive on Linux. ./models/User.js is different from ./models/user.js. Jest on Linux will fail where macOS or Windows passes.

3. Check package.json exports

{
  "name": "myapp",
  "exports": {
    "./utils/*": "./src/utils/*.js"
  },
  "jest": {
    "moduleNameMapper": {
      "^@/(.*)$": "<rootDir>/src/$1"
    }
  }
}

Some packages use the exports field in package.json to control module resolution. Jest picks this up in modern versions. If you have exports, make sure they point to the correct files.

Expected output after fix:

PASS  src/components/Header.test.js
  ✓ renders header (15 ms)
  ✓ displays user name (8 ms)

4. Use jest.config.ts for TypeScript

// jest.config.ts
import type { Config } from 'jest';

const config: Config = {
  preset: 'ts-jest',
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1'
  }
};

export default config;

For TypeScript projects, also sync with tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

The paths in tsconfig.json and moduleNameMapper must match exactly.

Prevention Tips

• Keep moduleNameMapper in sync with your bundler aliases
• Use __dirname or <rootDir> in paths, never relative ../ chains
• Add jest --showConfig to CI to verify module resolution on every run
• Use jest.mock() for external modules you don't want to resolve
• Test on Linux CI — case-sensitive resolution catches import casing bugs

Common Mistakes with cannot find module

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world JEST code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ