Module not found: Can't resolve a package or alias in Next.js
TypeScript and the bundler resolve imports separately. Align path aliases, workspace dependencies, exports conditions and filename case.

Introduction & Quick Summary
Module not found: Can't resolve 'x' stops next build before TypeScript or your tests ever see the file, and it names the importer, the request, and the list of locations Next tried. That last part is the useful one: the directories in the message show whether resolution stopped at a path alias, at node_modules, or at the project root.
The five causes, in the order they are worth checking:
- A path alias the bundler does not know about.
tsconfig.jsonpathsteaches TypeScript, not Turbopack or webpack;next.config.tshas to agree. - A dependency that is not installed at the root. pnpm and npm workspaces hoist differently, so a package reachable from a sibling workspace is not reachable from the app.
- An ESM-only package without an export for your condition.
exportscan omitrequireorbrowser, and the bundler then reports the package as missing. - A case mismatch.
./Components/Buttonresolves on macOS and fails on Linux CI, where the filesystem is case-sensitive. - A Node builtin imported into a client component.
fs,path, andcryptodo not exist in the browser bundle, and a"use client"boundary makes that an error rather than a shim.
| Message detail | What it points at | First check |
|---|---|---|
| Locations list only project folders | Alias or wrong relative path | tsconfig.json paths and next.config.ts |
Locations list node_modules of another workspace | Hoisting | Add the package to the app's own dependencies |
Package path ./x is not exported | Package exports map | The package's exports conditions |
| Fails on CI, passes locally | Case sensitivity | git ls-files versus the import string |
node: prefix in a client file | Server-only API | Move the import behind a server boundary |
Core Mechanics, Signatures & Reproducible Setup
Next.js resolves imports twice: once in the bundler (Turbopack by default in Next 16, webpack when configured) and once in TypeScript for types. Two resolvers means two places to configure, and they fail with different messages. TS reports TS2307: Cannot find module, the bundler reports Module not found: Can't resolve, and fixing only the tsconfig side leaves the build broken.
A reproducible failure takes one alias. This project compiles in the editor and fails in next build:
// tsconfig.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
}
}// src/app/page.tsx
import { Button } from "@/components/button";
export default function Page() {
return <Button />;
}next build answers with the resolved search paths:
./src/app/page.tsx:1:24
Module not found: Can't resolve '@/components/button'
1 | import { Button } from "@/components/button";
> Locations:
> ./src/app
> ./srcThe fix is to give the bundler the same mapping, in the config file the installed Next version documents:
// next.config.ts
import path from "node:path";
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
turbopack: {
resolveAlias: {
"@": path.join(process.cwd(), "src"),
},
},
};
export default nextConfig;On Next 15 and earlier the equivalent is webpack(config) { config.resolve.alias["@"] = ...; return config; }. Turbopack reads tsconfig.json paths for aliases in many cases, but only when baseUrl or the paths are relative in the shape it supports; an absolute alias defined only in a custom webpack config is invisible to it. That asymmetry is the most common reason a monorepo builds with --webpack and fails with the default bundler.
Key Comparison Table
Resolution failures are easier to classify by where the module should have come from than by the error text.
| Request | Resolved where | Fails when |
|---|---|---|
@/components/button | tsconfig paths + bundler alias | Only one side is configured |
react | app node_modules, then parent folders | Workspace hoisting puts it elsewhere |
some-esm-only | package exports, condition import | Your condition has no entry |
node:fs in a client component | browser bundle | Node builtins are not polyfilled |
./button with the wrong case | filesystem | Linux uses case-sensitive paths |
Keeping the two resolvers in step has no single switch in Next 16, but there is a dependable order: paths alone (TypeScript yes, Turbopack partly, webpack no), paths plus turbopack.resolveAlias (both yes, the monorepo default), package imports such as #ui/* (both yes with moduleResolution: bundler), or plain relative paths for small apps.
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
TypeScript passes and the build fails
Cannot find module from tsc and Module not found from the bundler are different resolvers. Read which one printed the error before editing anything, then confirm with the compiler's own trace:
npx tsc --noEmit --traceResolution | grep -A2 "@/"--traceResolution prints every candidate path it tried, including the paths substitution. If the trace shows the right file and next build still fails, the alias is the bundler's problem, not TypeScript's.
Workspace packages that resolve only from the root
In a pnpm workspace, a dependency declared at the root is not visible to an app whose node_modules is symlinked per package. Next resolves from the importing file upwards, so the app's own package.json has to list the package.
// apps/web/package.json
{
"dependencies": {
"@acme/ui": "workspace:*",
"class-variance-authority": "^0.7.1"
}
}If the module exists but a transitive import inside it fails, the message names the inner package. node-linker=hoisted in .npmrc hides this class of bug during development; it also hides it from your lockfile, so prefer declaring the dependency.
ESM-only packages and the exports map
A package can ship only import conditions. Importing it from a CommonJS context, or from a file the bundler treats as server-external, produces a resolution error that looks like a typo in the name.
{
"name": "tiny-esm",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
}
}
}Read the map before guessing:
node -e "console.log(JSON.stringify(require('tiny-esm/package.json').exports, null, 2))"
node --input-type=module -e "import('tiny-esm').then(m => console.log(Object.keys(m)))"When the missing condition is require, the fix is on the consumer side: dynamic await import() in a server component, or transpilePackages: ["tiny-esm"] when the package needs Next to compile it.
Case sensitivity, Windows, and macOS
import { Button } from "./components/Button" with a file named button.tsx works on macOS and fails on Linux. Git stores both names, so the file is committed and only CI notices. Make Git report the mismatch:
git config core.ignorecase false
git ls-files | grep -i "components/button"The quieter variant is a directory renamed only by case (UI to ui), where Git tracks the old spelling and the checkout on Linux keeps two folders. git mv UI ui-tmp && git mv ui-tmp ui records the rename explicitly.
Client components importing server-only modules
"use client" moves the module into the browser graph, where fs, path, node:crypto, and database clients do not exist. The error names the builtin and then fails the build:
"use client";
import { readFileSync } from "node:fs"; // Module not found: Can't resolve 'fs'Two legitimate fixes: move the call into a server component or route handler and pass plain data down, or mark the package as server-only so the mistake fails early with a clear message:
import "server-only";
export async function getUsers() {
const { readFileSync } = await import("node:fs");
return JSON.parse(readFileSync("data/users.json", "utf8"));
}server-only installs as a real package and produces a build error that names the offending client file. It is the cheapest guard against this class of bug in a codebase with many contributors.
Common Compilation/Runtime Mistakes & Version Gotchas
Editing jsconfig.json and tsconfig.json and assuming both apply. A Next project with TypeScript uses tsconfig.json only; a leftover jsconfig.json is ignored and its paths silently do nothing.
Aliasing @ to the project root. The root contains next.config.ts and app/, so @/app/... resolves and @/src/... does not, while the editor autocompletes both. Keep one src root and one alias.
Forgetting baseUrl when paths are relative. A paths entry without baseUrl is resolved relative to the tsconfig location; adding baseUrl: "." later moves every alias at once and breaks imports that had worked by accident.
Adding the package to the root package.json only. Install in the package that imports it, with pnpm add <pkg> --filter apps/web, then confirm with node -p "require.resolve('<pkg>')" executed from the app directory.
Deleting .next and calling it a fix. A stale .next cache can serve an old module graph, so rm -rf .next is a valid first test, but if the build then fails the same way, the cache was not the cause.
Assuming moduleResolution: "node" still works. Next 16 requires bundler or nodenext for package exports to resolve; the legacy node strategy ignores exports, so a package can appear installed and still be unreachable.
Version floor. turbopack.resolveAlias is stable in Next 16; Next 15 uses experimental.turbo.resolveAlias; server-only has been available since Next 13; exports conditions require Node 12.7 or newer for runtime and moduleResolution: bundler for TS.
A resolution error is a disagreement between two resolvers, so the fastest route is always to identify which one printed first. The JSON formatter catches a malformed tsconfig.json before you chase a missing module, and the diff tool makes a before-and-after alias review obvious.
Official references: TypeScript configuration in Next.js and Node's package entry points and exports.
Official references
primary documentationThe Next.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesnext/font: Failed to fetch a Google font during the build
The font is fetched during the build, not at runtime. Vendor it with next/font/local or give CI and Docker a route out.
Tailwind CSS 4: the PostCSS plugin error and the v3 leftovers behind it
The moved PostCSS plugin is only half of it. Match the config extension, drop autoprefixer and postcss-import, and check for a second v3 copy.
Next.js cacheComponents: 'used uncached or runtime data' build error
Cache Components makes the build refuse to guess where the static shell ends. Stream it, cache it with use cache, or declare the route blocking.
Vercel 504: FUNCTION_INVOCATION_TIMEOUT
A serverless invocation has a wall-clock budget. Measure it, stream or defer the work, and raise maxDuration only where it is earned.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.