Next.js Error: module_not_found — Module Not Found

./app/dashboard/page.tsx:3:0
Module not found: Can't resolve '@/components/UserCard'

  1 | import { Suspense } from 'react';
> 2 | import { UserCard } from '@/components/UserCard';
    |          ^
  3 |
  4 | export default function Dashboard() {

https://nextjs.org/docs/messages/module-not-found

Module not found is a build-time error — webpack or Turbopack tried to walk your import graph, hit a path it couldn’t resolve, and stopped. Unlike runtime errors, it’s deterministic: the same code, the same filesystem, the same lockfile produces the same result every time. That makes it one of the easier Next.js errors to fix once you know which of the five buckets you’re in: missing install, wrong path, missing alias, blocked subpath, or ignored file.

The build output always tells you the import that failed and the file it came from. Read those two lines first; everything else is verifying which bucket applies.

Why this happens

• Package missing from node_modules. You imported a package that isn't installed, or your lockfile has it but `npm install` was never run on this checkout. Common after pulling a branch with new deps, switching package managers (npm ↔ pnpm), or building in a Docker stage that doesn't COPY node_modules and doesn't run install.
• Wrong relative path or filename case. `./components/userCard` vs `./components/UserCard.tsx`. macOS and Windows treat these as the same; Linux (and your Vercel/Docker build) does not. Builds that pass locally and fail in CI are almost always case-sensitivity bugs.
• Path alias declared in tsconfig but not in the bundler config. TypeScript's `paths` (`@/*: ./src/*`) only affects type-checking. Next.js 13+ reads it automatically, but custom webpack configs, Jest, and older Next versions need the alias mirrored in `next.config.js` `webpack.resolve.alias` or in the test runner's moduleNameMapper.
• Module exists but uses a non-existent subpath export. Modern packages declare `exports` in their `package.json`. Importing `lodash/fp/curry` from a package that doesn't expose that subpath fails even though the file exists on disk. The error is identical: 'can't resolve …'.
• File ignored by `.dockerignore`, `.vercelignore`, or `.gitignore`. The file exists locally but never reaches the build environment. Common with `.env`-style files in `.dockerignore`, or a `dist/` folder that's gitignored but imported from.

How to fix it

Fixes are ordered by likelihood. Start with the first one that matches your context.

# Stop dev server first.
rm -rf node_modules .next
rm -f package-lock.json yarn.lock pnpm-lock.yaml  # only if mismatched
npm install                                       # or pnpm install / yarn

# If it's a Next.js cache issue specifically:
npx next build --no-lint

# See the real, tracked filename:
git ls-files | grep -i usercard

# Rename a file's case in Git (single-step, cross-platform-safe):
git mv components/userCard.tsx components/UserCard.tsx
git commit -m "fix: rename UserCard to match imports"

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

// BAD — react-icons subpath not exported in some versions
import { FaUser } from 'react-icons/fa/FaUser';

// GOOD — use the documented entry
import { FaUser } from 'react-icons/fa';

Detection and monitoring in production

Wire `next build` into CI on every PR — module-not-found errors are deterministic and always catchable in CI before they hit production. Add a `tsc --noEmit` step alongside; TypeScript catches missing-module errors faster than a full build. For monorepos, run a fresh checkout build (no cache) weekly to catch case-sensitivity bugs before someone's Linux-only deploy fails.