How to fix Cannot find module 'X' in TypeScript

What this error means

The "Cannot find module" error (TS2307) appears when TypeScript's module resolution system cannot locate the module you're trying to import. This can happen for several reasons: the package might not be installed in node_modules, the module may lack TypeScript type definitions, or the import path could be incorrect. TypeScript needs to understand both the runtime module location (where Node.js or your bundler will find it) and the type information for that module. When either piece is missing, you'll see this error even if the code would work in plain JavaScript. Common scenarios include: 1. **Missing packages**: The module is referenced in code but not installed via npm/yarn 2. **Missing type definitions**: The package exists but lacks TypeScript declarations (.d.ts files) 3. **Incorrect paths**: Relative imports with wrong file paths or missing file extensions 4. **Configuration issues**: tsconfig.json settings that prevent proper module resolution

Typical symptoms

• Compilation fails with 'Cannot find module' followed by the module name
• IDE shows red underlines on import statements
• Error code TS2307 appears in compiler output
• Code works in JavaScript but breaks when switching to TypeScript
• Imports work in some files but fail in others with identical syntax
• Recently installed packages show as unresolved in TypeScript

Common causes

1. The package is not installed in node_modules (missing npm install)
2. Missing @types package for JavaScript libraries without built-in types
3. Incorrect relative path in import statement (wrong directory or filename)
4. Module resolution mismatch in tsconfig.json (should be 'node' or 'node16')
5. Typo in module name or case sensitivity issue in import path
6. Package.json is missing or has incorrect module/exports configuration
7. Using path aliases in tsconfig.json without proper runtime support
8. File extension included in import when it shouldn't be (or vice versa)

How to fix "Cannot find module 'X'"

# Check if package is in package.json
cat package.json | grep "module-name"

# List installed packages
npm list module-name

# If not installed, install it
npm install module-name

# For React example:
npm install react react-dom

npx tsc
# or
npm run build

# General pattern
npm install --save-dev @types/package-name

# Common examples:
npm install --save-dev @types/node       # For Node.js APIs
npm install --save-dev @types/react      # For React
npm install --save-dev @types/lodash     # For Lodash
npm install --save-dev @types/express    # For Express

// This will now work
import express from "express";
import _ from "lodash";

// WRONG - incorrect relative path
import { formatDate } from "./utilities/formatDate";
// Error: Cannot find module './utilities/formatDate'

// CORRECT - fix the path
import { formatDate } from "./utils/formatDate";

// WRONG - missing ../ to go up a directory
import { User } from "./types/User";
// When types is in parent directory

// CORRECT
import { User } from "../types/User";

{
  "compilerOptions": {
    "moduleResolution": "node",
    "module": "commonjs",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "typeRoots": ["./node_modules/@types"],
    "baseUrl": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

{
  "compilerOptions": {
    "moduleResolution": "node16",
    "module": "node16"
  }
}

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "esnext"
  }
}

// WRONG - incorrect casing
import React from "react";     // ✓ Correct
import React from "React";     // ✗ Won't work on Linux

// WRONG - typo in package name
import express from "expres";  // Missing 's'
import _ from "loadash";       // Should be "lodash"

// WRONG - incorrect file casing
import { User } from "./Types/user";  // File is ./types/User.ts

# Remove node_modules and lock file
rm -rf node_modules
rm package-lock.json  # or yarn.lock / pnpm-lock.yaml

# Clear npm cache
npm cache clean --force

# Reinstall everything
npm install

# Restart TypeScript server in VS Code:
# Press Cmd/Ctrl + Shift + P, then "TypeScript: Restart TS Server"

# If using npm workspaces
npm install --workspaces

# If using yarn workspaces
yarn install

# If using pnpm
pnpm install

Advanced notes

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
      "@utils/*": ["utils/*"]
    }
  }
}

import { Button } from "@components/Button";

// tsconfig.json
{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node"
  }
}

// Import syntax
import express from "express";  // Compiled to: const express = require("express")

// package.json
{
  "type": "module"
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "node16",
    "moduleResolution": "node16"
  }
}

// WRONG with Node16
import { formatDate } from "./utils/formatDate";

// CORRECT with Node16 (even though source file is .ts)
import { formatDate } from "./utils/formatDate.js";

// types/my-untyped-lib.d.ts
declare module "my-untyped-lib" {
  export function doSomething(param: string): number;
  export interface Config {
    enabled: boolean;
  }
}

{
  "include": ["src/**/*", "types/**/*"]
}

module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
    alias: {
      '@components': path.resolve(__dirname, 'src/components/')
    }
  }
};

npx tsc --traceResolution | grep "module-name"

Frequently asked questions

What does "TS2307" mean?

The "Cannot find module" error (TS2307) appears when TypeScript's module resolution system cannot locate the module you're trying to import. This can happen for several reasons: the package might not be installed in node_modules, the module may lack TypeScript type definitions, or the import path could be incorrect. js or your bundler will find it) and the type information for that module.

How do I fix "TS2307"?

This TypeScript error occurs when the compiler cannot resolve an imported module, either because it's not installed, has no type definitions, or the import path is incorrect. The fix typically involves installing the package, adding type definitions, or correcting the module path.

What causes "TS2307"?

The package is not installed in node_modules (missing npm install) Missing @types package for JavaScript libraries without built-in types Incorrect relative path in import statement (wrong directory or filename)

Is the "TS2307" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• Cannot find module 'next'

  Cannot find module 'next'

  MEDIUM

• Cannot export member 'X' in namespace

  How to fix 'Cannot export member X in namespace' in TypeScript

  MEDIUM

• Cannot find module 'react'

  Cannot find module 'react'

  HIGH

• Cannot destructure into a non-binding pattern

  How to fix 'Cannot destructure into a non-binding pattern' in TypeScript

  MEDIUM

• Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

  How to fix "Cannot find name 'process'" in TypeScript

  MEDIUM

• Module has no exported member 'X'

  How to fix 'Module has no exported member X' error in TypeScript

  MEDIUM

Official resources & further reading

• 📚TypeScript Official Documentation
• 📖
  TypeScript Handbook - Module Resolution(Official Docs)
• 📖
  TypeScript TSConfig - moduleResolution(Official Docs)
• 📖
  TypeScript Handbook - Modules Theory(Official Docs)
• Tim Mouskhelichvili - Fixing Cannot Find Module Error
• BobbyHadz - Cannot Find Module Error Solved
• Stack Overflow - TypeScript Module Resolution
• 🐙
  TypeScript GitHub - TS2307 Issues(GitHub)
• Better Stack - Understanding Module Resolution in TypeScript