Cache handler ERR_MODULE_NOT_FOUND when using ESM modules

Why this is a good first issue

Issue involves ESM module resolution and path handling complexities.

AI Summary

The issue arises from using `import.meta.resolve` in an ESM context, which returns a file URL that Next.js incorrectly concatenates with `.next/`. The solution likely involves proper path handling or module format adjustments, but the exact fix requires understanding Next.js internals and Node.js module resolution.

Issue Description

Link to the code that reproduces this issue

https://github.com/hdodov/test-nextjs/tree/cache-handler-not-working

To Reproduce

Clone the repo https://github.com/hdodov/test-nextjs/tree/cache-handler-not-working
npm i
npm run dev
You'll see the error

Current vs. Expected behavior

I have "type": "module" in my package.json, so I can't add the cache handler like this, as the docs suggest:

module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // disable default in-memory caching
}

Instead, I need to add it like this:

module.exports = {
- cacheHandler: require.resolve('./cache-handler.js'),
+ cacheHandler: import.meta.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // disable default in-memory caching
}

However, when I do so, I get the following error on npm run dev:

$ npm run dev

> [email protected] dev
> next dev

   ▲ Next.js 15.1.0
   - Local:        http://localhost:3000
   - Network:      http://192.168.100.16:3000

 ✓ Starting...
 ✓ Ready in 1625ms
[Error: Cannot find module '/Users/hristiyan.dodov/Projects/test-nextjs/.next/file:/Users/hristiyan.dodov/Projects/test-nextjs/cache-handler.js' imported from /Users/hristiyan.dodov/Projects/test-nextjs/node_modules/next/dist/server/next-server.js] {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///Users/hristiyan.dodov/Projects/test-nextjs/.next/file:/Users/hristiyan.dodov/Projects/test-nextjs/cache-handler.js'
}

…and I also get it if I try npm run build directly:

$ npm run build

> [email protected] build
> next build

   ▲ Next.js 15.1.0

   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types    

> Build error occurred
[Error: Cannot find module '/Users/hristiyan.dodov

GitHub Labels

buglinear: nextModule Resolution