← Cheatsheets / Error Fixes

How to Fix ModuleNotFoundError

ModuleNotFoundError or 'Cannot find module' breaking your build? Here's why it happens and how to fix it in JavaScript, Python, and TypeScript.

ModuleNotFoundError imports debugging npm pip error-fix

Your AI wrote the code. You ran it. “Module not found.” This error means the code is trying to import something that doesn’t exist — wrong package name, missing install, or incorrect file path.

It’s one of the most frequent errors in AI-generated code because AI tools often hallucinate package names, use outdated imports, or assume you’ve already installed dependencies.

What Does This Error Mean?

In plain English: “I can’t find the thing you’re trying to import.”

The runtime or bundler looked for a module (a package, file, or library) and couldn’t locate it. The import statement points somewhere that doesn’t exist.

Common Variations

# JavaScript / TypeScript
Module not found: Can't resolve 'some-package'
Cannot find module 'some-package' or its corresponding type declarations
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/path/to/file'

# Python
ModuleNotFoundError: No module named 'some_package'
ImportError: cannot import name 'something' from 'some_module'

5 Common Causes

1. Package Not Installed

AI used a package but didn’t tell you to install it.

# JavaScript — check if it's in package.json
npm ls some-package

# If not found, install it:
npm install some-package

# Python — check if installed
pip show some-package

# If not found:
pip install some-package

2. AI Hallucinated a Package Name

AI invented a package that doesn’t exist. This is surprisingly common.

// AI wrote:
import { formatDate } from 'date-helpers';  // ← doesn't exist

// The real package might be:
import { format } from 'date-fns';
// or
import dayjs from 'dayjs';

How to check: Search for the package on npmjs.com or PyPI. If it doesn’t exist, ask AI: “What’s the correct package name for [functionality]?“

3. Wrong File Path

Relative imports are tricky. AI often gets the directory structure wrong.

// AI wrote (wrong path):
import { Button } from '../components/ui/Button';

// But your actual structure is:
import { Button } from '@/components/ui/Button';  // using path alias
// or
import { Button } from '../../components/ui/Button';  // different depth

4. Missing Type Declarations (TypeScript)

The package exists but TypeScript can’t find types for it.

# Error: Could not find a declaration file for module 'some-package'

# Fix: Install the types package
npm install -D @types/some-package

# If no types exist, create a declaration file:
# src/types/some-package.d.ts
declare module 'some-package';

5. Wrong Python Environment

You installed the package, but in a different virtual environment.

# Check which Python you're using
which python
which pip

# Make sure you're in the right venv
source venv/bin/activate  # or .venv/bin/activate
pip install some-package

Step-by-Step Fix Process

Step 1: Identify the Missing Module

Read the error message carefully:

Module not found: Can't resolve 'framer-motion'

The missing module is framer-motion.

Step 2: Check If It Should Be Installed

# JavaScript
cat package.json | grep "framer-motion"

# Python
pip list | grep framer

Step 3: Install or Fix the Import

If it’s a real package — install it:

npm install framer-motion    # JavaScript
pip install framer-motion    # Python

If it’s a local file import — fix the path:

# Find the actual file
find src -name "Button*" -type f

# Then fix the import path to match

If AI hallucinated it — find the real package:

Ask AI: "I need [functionality]. What's the correct npm/pip package name? 
Give me the exact import statement."

Step 4: Clear Cache and Restart

Sometimes the module is installed but cached incorrectly:

# JavaScript
rm -rf node_modules/.cache
# or full reset:
rm -rf node_modules package-lock.json
npm install

# Python
pip cache purge
pip install -r requirements.txt

# Next.js specifically
rm -rf .next
npm run dev

Framework-Specific Fixes

Next.js Path Aliases

// tsconfig.json — set up @ alias
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Vite / Astro Path Aliases

// vite.config.js or astro.config.mjs
import { resolve } from 'path';

export default {
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
};

Python Relative Imports

# If you get: ImportError: attempted relative import with no known parent package
# Make sure every directory has an __init__.py file
# And run as a module: python -m mypackage.module

🤖 Prompt to Fix This

I'm getting this module not found error:

[PASTE THE FULL ERROR MESSAGE]

My project uses: [framework, e.g., Next.js 14 / Python 3.11 / Astro]
Package manager: [npm / yarn / pnpm / pip]

Here's my import statement:
[PASTE THE IMPORT LINE]

Please:
1. Is this a real package or did you hallucinate it?
2. What's the correct package name and import statement?
3. Give me the exact install command
4. If it's a file import, what should the correct path be?

Prevention Tips

  1. After AI generates code, scan all imports — verify each package exists before running
  2. Tell AI what’s already installed — paste your package.json dependencies or requirements.txt
  3. Set up path aliases early — @/ imports are cleaner and less error-prone
  4. Use AI to generate install commands — “List all npm packages I need to install for this code”
  5. Pin your Python virtual environment — always work inside venv
✓ Copied to clipboard!