Next.js build fails on a Node.js module like net or node:buffer in browser code
Module not found: Can't resolve 'net'Short answer
These errors mean a Node.js built-in (net, fs, node:buffer) is being bundled for the browser, where it does not exist. Find the import chain that pulls it into a Client Component, move that work to the server, or tell the bundler to stub the module for the browser build only.
Fix it fast
1Find out which cause you have
Read the import trace in the error. It lists the files from the failing module up to the entry. The first of your own files in that list is the one to change.
npx next build2Match what you see, then jump to its fix
- 1
The trace ends in a file that has 'use client' at the top, or in one imported by itServer-only code is imported by a Client ComponentFix - 2
The trace points into node_modules, in a package meant for browsers (a socket or STOMP client, for example)A browser library asks for a Node.js built-in it does not use in the browserFix
- 1
What does the error look like?
Module not found: Can't resolve 'net'UnhandledSchemeError: Reading from "node:buffer" is not handled by plugins
Cause 1 of 2
Server-only code is imported by a Client Component
1Check
Everything a 'use client' file imports is bundled for the browser. A database client, an fs helper or any library using Node.js built-ins pulled in there fails to resolve.
grep -rln "use client" app/ components/ | xargs grep -ln "from '@/lib"2Fix
Keep that code in a Server Component or a route handler and pass only the result to the client. Mark the server-only module so a wrong import fails with a clear message.
npm install server-only
// lib/data.ts
import 'server-only'3Verify
Build again. An import of that module from a Client Component now stops with a message naming the file, and the Node.js module error is gone once the import is removed.
npx next buildConfirmed by nextjs.org
Cause 2 of 2
A browser library asks for a Node.js built-in it does not use in the browser
1Check
Webpack 5 no longer polyfills Node.js core modules. A package that requires one for a code path only used on the server fails when bundled for the browser.
npm ls stompjs2Fix
Stub the module for the browser build. With Turbopack, the default bundler, alias it with the browser condition to an empty file. With webpack, set resolve.fallback to false when isServer is false.
// next.config.js (Turbopack)
module.exports = {
turbopack: {
resolveAlias: {
net: { browser: './empty.js' },
},
},
}
// next.config.js (webpack, next build --webpack)
module.exports = {
webpack: (config, { isServer }) => {
if (!isServer) {
config.resolve.fallback = { ...config.resolve.fallback, net: false }
}
return config
},
}3Verify
Add an empty empty.js file in the project root for the Turbopack variant, rebuild, and open the page that uses the library.
npx next buildConfirmed by nextjs.org
How do I stop it coming back?
- Add the 'use client' directive only to the small interactive leaf components, not to whole pages.
- Import 'server-only' at the top of every module that touches secrets, files or a database.
- Check the import trace in the first build error before adding any config.
- Prefer a browser build of a library over stubbing Node.js modules, when the library offers one.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix