@next/mdx: unhandled promise rejection when plugin path fails to resolve in mdx-js-loader
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 74/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- javascript, markdown, nextjs, webpack
- Domain
- build-system, tooling
Research direction
Inspect packages/next-mdx/mdx-js-loader.js around line 61, starting with the getOptions() promise and its interaction with the webpack loader callback. Run the linked reproduction with npm install and npm run build. Done means an invalid plugin path produces a clear webpack-reported module-resolution error instead of an unhandled rejection or hanging build.
Written by the indexing model from the issue text.
Description
Link to the code that reproduces this issue
https://github.com/Jinoko01/mdx-catch-bug
To Reproduce
- Clone the reproduction repo
- Run
npm install - Run
npm run build(next build --webpack) - Observe the build hangs indefinitely or throws UnhandledPromiseRejection
Current vs. Expected behavior
Current:
The build process hangs without any error message, or Node.js throws
an UnhandledPromiseRejection without webpack properly reporting the error.
node:internal/process/promises:288
UnhandledPromiseRejection: Cannot find module 'remark-plugin-does-not-exist'
Expected:
Webpack should receive the error via callback and report it clearly:
Error: Cannot find module 'remark-plugin-does-not-exist'
Require stack: ...
Provide environment information
Operating System:
Platform: win32
Arch: x64
Version: Windows 11 Enterprise
Available memory (MB): 32488
Available CPU cores: 16
Binaries:
Node: 24.14.0
npm: 11.9.0
Yarn: N/A
pnpm: 11.1.1
Relevant Packages:
next: 16.3.0-canary.29 // Latest available version is detected (16.3.0-canary.29).
eslint-config-next: N/A
react: 19.2.6
react-dom: 19.2.6
typescript: 5.9.3
Next.js Config:
output: N/A
Which area(s) are affected? (Select all that apply)
Markdown (MDX), Webpack
Which stage(s) are affected? (Select all that apply)
next build (local)
Additional context
Root cause: In packages/next-mdx/mdx-js-loader.js, the Promise returned by getOptions() is missing a .catch() handler. When a plugin string path
fails to resolve (e.g., module not found, ESM import failure), the rejection
is never forwarded to webpack's callback, causing the build to stall.
// Current code (line 61)
getOptions(options, this.context).then((userProvidedMdxOptions) => {
mdxLoader.call(proxy, ...args)
})
// Missing: .catch((error) => callback(error))
- Dominant language
- JavaScript
- Stars
- 142k
- Forks
- 32.5k
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 314
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from vercel/next.js
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
Image (next/image)
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Loading UI and Streaming
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
HarperFast/skills#96 ·
-
[Block] Latest Posts [Type] Bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
sugarlabs/musicblocks#8847 ·