Introduction
When migrating a project to the latest version of Next.js, developers often face the “Module not found” error. This error usually appears because of changes in folder structure, import paths, updated Next.js rules, missing packages, or outdated configurations. These issues can break your build and stop your application from running. In this article, we will understand why this error happens and how to fix it step by step in simple, beginner-friendly language.
Why “Module Not Found” Error Happens After Migration
Several reasons can trigger this error during a Next.js version upgrade. Let’s break them down clearly.
1. Incorrect or Old Import Paths
Your old project may still contain imports pointing to files or folders that have been moved, renamed, or deleted.
Example:
import Header from "../components/Header";
If the components folder was renamed to ui, this import will break.
2. Missing Packages After Migration
During migration, some node modules may not install correctly or may be removed due to version conflicts.
Example error:
Module not found: Can't resolve 'axios'
This simply means the dependency is not installed or has an incompatible version.
3. Unsupported Aliases or Incorrect tsconfig/jsconfig Settings
If your project uses path aliases like @/components, they may break after upgrade if the configuration is not updated.
Example:
import Navbar from '@/components/Navbar';
If baseUrl or paths are missing in jsconfig.json, Next.js cannot resolve the module.
4. App Router vs Pages Router Path Issues
Next.js latest versions prefer the app router, and migration can break imports referencing old folder structures.
Example:
If you moved to app/ directory but imports still refer to pages/, errors will occur.
5. Deleted or Renamed File Extensions
Next.js may reject files with unsupported extensions or changed naming conventions.
Example:
Header.jsx → Header.tsx
If imports were not updated to match new file names, the module cannot be found.
Step-by-Step Fixes for “Module Not Found” Errors in Next.js
Below are the most effective solutions used by developers during migration.
1. Check and Update All Import Paths
Verify that your imports point to the correct location.
// Wrong
import Button from '../ui/button';
// Correct
import Button from '../components/ui/button';
Use VS Code "Find and Replace" to quickly update renamed folders.
2. Reinstall All Node Modules
Sometimes the simplest fix is reinstalling dependencies.
rm -rf node_modules package-lock.json
npm install
Or if using yarn:
yarn install --force
This resolves corrupted or missing packages.
3. Install Missing Dependencies
If the error shows a missing package name, install it directly.
npm install axios
Or update incompatible ones:
npm install next@latest react@latest react-dom@latest
4. Fix Path Aliases in jsconfig.json / tsconfig.json
Add or update alias settings.
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./*"]
}
}
}
Restart your dev server:
npm run dev
5. Verify Folder Structure After Migration
Make sure your folder structure matches Next.js best practices.
Correct structure:
app/
page.js
layout.js
components/
lib/
public/
If files were moved accidentally, restore them or update imports.
6. Clear the Next.js Cache
Sometimes cached builds cause module resolution errors.
npm run build --no-cache
Or manually remove .next folder:
rm -rf .next
7. Fix Missing File Extensions
Ensure all imports match actual file extensions.
import Header from './Header.jsx'; // not Header.js
Next.js doesn’t auto-detect mismatched extensions.
8. Validate Packages Compatibility
Some third-party packages may not support the newest Next.js version.
Check their documentation or install compatible versions.
Example:
npm install next-auth@latest
9. Use Absolute Imports Instead of Relative Ones
Long relative paths can break after migration.
// Instead of this
import Card from '../../../components/Card';
// Use this
import Card from '@/components/Card';
Absolute imports reduce errors and make code cleaner.
Best Practices to Prevent “Module Not Found” Errors
Keep folder names consistent
Avoid renaming folders frequently during migration.
Use TypeScript for early error detection
TS shows import errors before you run the app.
Always check release notes
Next.js major updates introduce breaking changes that must be followed.
Regularly clean cache and reinstall node modules
This ensures your environment stays fresh and error-free.
Summary
Migrating to the latest version of Next.js often triggers “Module not found” errors because of missing packages, incorrect paths, outdated aliases, folder structure changes, or incompatible dependencies. By checking import paths, reinstalling modules, fixing alias configurations, clearing cache, and updating folder structure, you can quickly resolve these issues and ensure a smooth Next.js upgrade experience.