Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Next.js build fails on a Node.js module like net or node:buffer in browser code

ErrorModule 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.

  • Applies to Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 build
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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

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 build

Confirmed by nextjs.org

Did this fix it?

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 stompjs

2Fix

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 build

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.