nextjs - ✅(Solved) Fix Launching Next.js app with "--experimental-network-inspection" passed to Node.js causes Next.js fail to start [1 pull requests, 2 comments, 3 participants]

nextjs2025-12-25 13:32:59

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

vercel/next.js#87794•Fetched 2026-04-08 02:06:07

View on GitHub

Comments

Participants

Timeline

Reactions

Author

Participants

Timeline (top)

subscribed ×5labeled ×4commented ×2closed ×1

Error Message

From the error logs it seems that newer Next.js version try to put the flag under NODE_OPTIONS, which Node.js doesn't allow

Root Cause

The Next.js dev server should start, but it immediately stops debugging session because the process is immediately terminated.

Fix Action

Fixed

Fixed by PR: Allow Node.js' experimental inspector flags in next dev and next build (https://github.com/vercel/next.js/pull/90603)

PR fix notes

PR #90603: Allow Node.js' experimental inspector flags in `next dev` and `next build`

Repository: vercel/next.js
Author: eps1lon
State: closed | merged: True
Link: https://github.com/vercel/next.js/pull/90603

Description (problem / solution / changelog)

Fixes https://github.com/vercel/next.js/issues/87794 Fixes https://linear.app/vercel/issue/NEXT-4863/

Certain Node.js options are only supported as CLI args and not via a NODE_OPTIONS environment variable. However, next dev was always passing along CLI args to NODE_OPTIONS.

Now we forward a curated list of Node.js CLI args as CLI args to the dev server. Most interestingly, this enables having Node.js' experimental Network inspector running (-experimental-network-inspection) to enable the Network tab of Chrome DevTools when attached to Node.js.

All allowed CLI-only flags:

--experimental-network-inspection
--experimental-storage-inspection
--experimental-worker-inspection
--experimental-inspector-network-resource

next start was already working.

Holding off on adding better support via next dev --experimental-network-inspection because it's an experimental flag and I'm not too familiar with the current state.

Changed files

packages/next/src/cli/next-dev.ts (modified, +5/-1)
packages/next/src/lib/worker.ts (modified, +5/-1)
packages/next/src/server/lib/utils.test.ts (modified, +27/-3)
packages/next/src/server/lib/utils.ts (modified, +55/-22)
test/e2e/node-cli-args/app/layout.tsx (added, +14/-0)
test/e2e/node-cli-args/app/page.tsx (added, +4/-0)
test/e2e/node-cli-args/node-cli-args.test.ts (added, +19/-0)

Code Example

node --inspect --experimental-network-inspection ./node_modules/next/dist/bin/next --port 3000
# either including or omitting 'dev' behaves the same
node --inspect --experimental-network-inspection ./node_modules/next/dist/bin/next dev --port 3000

---

Debugger attached.
/Users/user/.local/share/fnm/node-versions/v24.12.0/installation/bin/node: --experimental-network-inspection is not allowed in NODE_OPTIONS

Waiting for the debugger to disconnect...

---

Debugger attached.
Debugger attached.
   the --inspect option was detected, the Next.js router server should be inspected at 9230.
Debugger attached.
Debugger attached.
[baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`
   ▲ Next.js 16.0.2-canary.0 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://192.168.0.193:3000

 ✓ Starting...
 ✓ Ready in 2.9s
 GET / 200 in 758ms (compile: 654ms, render: 104ms)
 GET / 200 in 132ms (compile: 11ms, render: 121ms)
Debugger attached.
Debugger attached.
 POST / 200 in 258ms (compile: 9ms, render: 249ms)

---

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.2.0: Tue Nov 18 21:08:48 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T8132
  Available memory (MB): 16384
  Available CPU cores: 10
Binaries:
  Node: 24.12.0
  npm: 11.7.0
  Yarn: 1.22.22
  pnpm: 10.26.0
Relevant Packages:
  next: 16.1.1-canary.5 // Latest available version is detected (16.1.1-canary.5).
  eslint-config-next: N/A
  react: 19.2.3
  react-dom: 19.2.3
  typescript: 5.9.3
Next.js Config:
  output: N/A

RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://github.com/U3erKa/nextjs-network-inspection-reproduction-app

To Reproduce

Launch reproduction repo via VSCode debugger by pressing F5. Alternatively, run in shell:

node --inspect --experimental-network-inspection ./node_modules/next/dist/bin/next --port 3000
# either including or omitting 'dev' behaves the same
node --inspect --experimental-network-inspection ./node_modules/next/dist/bin/next dev --port 3000

Current vs. Expected behavior

The Next.js dev server should start, but it immediately stops debugging session because the process is immediately terminated.

From the error logs it seems that newer Next.js version try to put the flag under NODE_OPTIONS, which Node.js doesn't allow

Debugger attached.
/Users/user/.local/share/fnm/node-versions/v24.12.0/installation/bin/node: --experimental-network-inspection is not allowed in NODE_OPTIONS

Waiting for the debugger to disconnect...

In working Next.js versions the logs look something like:

Debugger attached.
Debugger attached.
   the --inspect option was detected, the Next.js router server should be inspected at 9230.
Debugger attached.
Debugger attached.
[baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`
   ▲ Next.js 16.0.2-canary.0 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://192.168.0.193:3000

 ✓ Starting...
 ✓ Ready in 2.9s
 GET / 200 in 758ms (compile: 654ms, render: 104ms)
 GET / 200 in 132ms (compile: 11ms, render: 121ms)
Debugger attached.
Debugger attached.
 POST / 200 in 258ms (compile: 9ms, render: 249ms)

To verify that network inspection is enabled open Chrome devtools and then open devtols for Node.js:

By also passing '--experimental-network-inspection' the Node.js devtools show fetch requests sent by Node.js process when "Run server-side fetch" button is clicked:

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.2.0: Tue Nov 18 21:08:48 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T8132
  Available memory (MB): 16384
  Available CPU cores: 10
Binaries:
  Node: 24.12.0
  npm: 11.7.0
  Yarn: 1.22.22
  pnpm: 10.26.0
Relevant Packages:
  next: 16.1.1-canary.5 // Latest available version is detected (16.1.1-canary.5).
  eslint-config-next: N/A
  react: 19.2.3
  react-dom: 19.2.3
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Runtime, Testing, Not sure

Which stage(s) are affected? (Select all that apply)

next dev (local)

Additional context

I tested against Next.js versions:

Release:
- Latest known working version: "16.0.2"
- Broken versions: ">=16.0.3", including the latest "16.1.1"
Canary:
- Latest known working version: "16.0.2-canary.0"
- Broken versions: ">=16.0.2-canary.1", including the latest "16.1.1-canary.5"

extent analysis

TL;DR

The issue can be worked around by using an older version of Next.js that supports the --experimental-network-inspection flag without putting it under NODE_OPTIONS.

Guidance

The error message indicates that the --experimental-network-inspection flag is not allowed in NODE_OPTIONS, which is a change in behavior introduced in newer versions of Next.js.
To verify the issue, run the reproduction repo with the latest version of Next.js and check the error logs.
To mitigate the issue, try downgrading to a known working version of Next.js, such as 16.0.2 or 16.0.2-canary.0.
If downgrading is not feasible, consider opening an issue with the Next.js team to request support for the --experimental-network-inspection flag in newer versions.

Example

No code snippet is provided as the issue is related to a specific version of Next.js and its interaction with the --experimental-network-inspection flag.

Notes

The workaround may not be suitable for all users, especially those who rely on features introduced in newer versions of Next.js. Additionally, the issue may be resolved in future versions of Next.js, so it's essential to keep an eye on the project's progress.

Recommendation

Apply workaround: Downgrade to a known working version of Next.js, such as 16.0.2 or 16.0.2-canary.0, to enable the use of the --experimental-network-inspection flag. This is a temporary solution until the issue is resolved in newer versions of Next.js.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#installation #model compatibility #GPU setup #container setup #orchestration issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering

nextjs - ✅(Solved) Fix Launching Next.js app with "--experimental-network-inspection" passed to Node.js causes Next.js fail to start [1 pull requests, 2 comments, 3 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fixed

PR fix notes

PR #90603: Allow Node.js' experimental inspector flags in `next dev` and `next build`

Description (problem / solution / changelog)

Changed files

Code Example

Link to the code that reproduces this issue

To Reproduce

Current vs. Expected behavior

Provide environment information

Which area(s) are affected? (Select all that apply)

Which stage(s) are affected? (Select all that apply)

Additional context

extent analysis

TL;DR

Guidance

Example

Notes

Recommendation

Still need to ship something?

TRENDING

nextjs - ✅(Solved) Fix Launching Next.js app with "--experimental-network-inspection" passed to Node.js causes Next.js fail to start [1 pull requests, 2 comments, 3 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Fix Action

Fixed

PR fix notes

PR #90603: Allow Node.js' experimental inspector flags in next dev and next build

Description (problem / solution / changelog)

Changed files

Code Example

Link to the code that reproduces this issue

To Reproduce

Current vs. Expected behavior

Provide environment information

Which area(s) are affected? (Select all that apply)

Which stage(s) are affected? (Select all that apply)

Additional context

extent analysis

TL;DR

Guidance

Example

Notes

Recommendation

Still need to ship something?

RELATED_DISCOVERY

TRENDING

PR #90603: Allow Node.js' experimental inspector flags in `next dev` and `next build`