Skip to content

Commit 2f259a4

Browse files
authored
node: withhold --enable-source-maps on every Node 26.x below 26.8 (nodejs/node#63169) (#784)
1 parent 2cd321e commit 2f259a4

4 files changed

Lines changed: 41 additions & 29 deletions

File tree

‎crates/nub-core/src/node/flags.rs‎

Lines changed: 35 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -15,27 +15,38 @@ use super::version::NodeVersion;
1515
/// Flags Nub injects on EVERY supported Node version where they are safe.
1616
/// `--enable-source-maps` has existed since Node 12.12, so it is structurally
1717
/// available across the whole 18.19+ range — BUT it is gated out of the
18-
/// `source_maps_safe`-false band (Node 26.2.x; see that predicate).
18+
/// `source_maps_safe`-false band (Node 26.0.0–26.7.x; see that predicate).
1919
/// (`--disable-warning` is NOT here — it doesn't exist on Node 18.x / 20.0–20.10
2020
/// and is gated below; injecting it there is a hard "bad option" / "not allowed
2121
/// in NODE_OPTIONS" error, which broke the compat tier on those versions.)
2222
const ALWAYS_INJECT: &[&str] = &["--enable-source-maps"];
2323

2424
/// Whether nub may inject `--enable-source-maps` on this Node version.
2525
///
26-
/// Node **26.2.x specifically** has a regression where, with source maps enabled,
27-
/// a no-message `assert.ok(false)` / `assert(false)` rethrows as a `TypeError`
28-
/// instead of the expected `AssertionError` (the source-map remapping path
29-
/// mis-constructs the error for the no-message form). Empirically isolated to the
30-
/// 26.2 patch band: Node 18.19 / 20 / 22 / 24 / 25 and 26.1 are all clean, and a
31-
/// future 26.3 is expected clean too. So nub withholds the injection ONLY on
32-
/// 26.2.x — source maps are unavailable there (a cosmetic loss: stack traces are
33-
/// not remapped), which is far better than corrupting the type of a thrown
34-
/// AssertionError. Verified on real Node 26.2.0:
26+
/// The whole **Node 26.x** line released so far regresses (nodejs/node#63169):
27+
/// with source maps enabled and no source map for the file, the remapping path's
28+
/// `getErrorSourceLocation` returns `undefined`, so a no-message
29+
/// `assert(false)` / `assert.ok(false)` / `assert.strict(false)` throws
30+
/// `TypeError [ERR_INVALID_ARG_TYPE]` ("The \"message\" argument …") instead of
31+
/// the expected `AssertionError`. Verified on real 26.0.0 / 26.3.0 / 26.5.1 /
32+
/// 26.7.0; 25.x is clean (25.9.0 yields an `AssertionError` with a degraded
33+
/// message, which is the right TYPE). This band was previously — and wrongly —
34+
/// documented as 26.2-only.
35+
///
36+
/// Fixed on Node `main` by b5d37cd4 (nodejs/node#63215, 2026-08-20) in
37+
/// `lib/internal/errors/error_source.js`, which is in NO release yet (latest is
38+
/// v26.7.0, 2026-08-05). 26.8.0 is therefore the first release that can carry
39+
/// the fix, so the band is closed there — a **stopgap pending that release**.
40+
/// RE-VERIFY when 26.8.0 ships, and move the boundary up if it does not carry
41+
/// the fix:
3542
/// `node --enable-source-maps -e 'try{require("assert").ok(false)}catch(e){console.log(e.constructor.name)}'`
36-
/// prints `TypeError`; without the flag it prints `AssertionError`.
43+
/// must print `AssertionError`, not `TypeError`.
44+
///
45+
/// The trade-off is unchanged: withholding costs only stack-trace remapping (a
46+
/// cosmetic loss), while injecting corrupts the TYPE of a thrown AssertionError,
47+
/// which breaks `node:test` assertions outright.
3748
fn source_maps_safe(node_version: &NodeVersion) -> bool {
38-
!(node_version.major() == 26 && node_version.minor() == 2)
49+
!(node_version.major() == 26 && *node_version < NodeVersion::new(26, 8, 0))
3950
}
4051

4152
/// `--disable-warning=ExperimentalWarning` (suppresses Node's experimental-feature
@@ -353,8 +364,9 @@ pub fn compute_inject_flags(
353364
let mut flags: Vec<&str> = Vec::new();
354365

355366
for &flag in ALWAYS_INJECT {
356-
// --enable-source-maps is withheld on Node 26.2.x (see `source_maps_safe`):
357-
// there it turns a no-message AssertionError into a TypeError.
367+
// --enable-source-maps is withheld below Node 26.8 on the 26.x line (see
368+
// `source_maps_safe`): there it turns a no-message AssertionError into a
369+
// TypeError.
358370
if flag == "--enable-source-maps" && !source_maps_safe(&node_version) {
359371
continue;
360372
}
@@ -1124,12 +1136,13 @@ mod tests {
11241136
}
11251137

11261138
#[test]
1127-
fn source_maps_withheld_only_on_26_2_band() {
1128-
// Node 26.2.x regresses: with --enable-source-maps, a no-message
1129-
// assert.ok(false) rethrows as TypeError instead of AssertionError. nub
1130-
// withholds the injection there and ONLY there — 24 / 25 / 26.1 and a
1131-
// future 26.3 are clean. (Verified empirically on real Node 26.2.0.)
1132-
for ver in [v(24, 0, 0), v(25, 8, 0), v(26, 1, 0), v(26, 3, 0)] {
1139+
fn source_maps_withheld_across_the_whole_26_x_regression_band() {
1140+
// Every Node 26.x below 26.8 regresses (nodejs/node#63169): with
1141+
// --enable-source-maps, a no-message assert.ok(false) throws TypeError
1142+
// [ERR_INVALID_ARG_TYPE] instead of AssertionError. The band's EDGES are
1143+
// what this pins — 25.9.0 below it, 26.8.0 (first release that can carry
1144+
// the upstream fix b5d37cd4) and 27.0.0 above it.
1145+
for ver in [v(24, 0, 0), v(25, 9, 0), v(26, 8, 0), v(27, 0, 0)] {
11331146
assert!(
11341147
source_maps_safe(&ver),
11351148
"source maps must be safe to inject on {ver:?}"
@@ -1140,8 +1153,8 @@ mod tests {
11401153
"--enable-source-maps must inject on {ver:?}"
11411154
);
11421155
}
1143-
// The affected band: every 26.2.x patch is gated out.
1144-
for ver in [v(26, 2, 0), v(26, 2, 5)] {
1156+
// The affected band: 26.0.0 through 26.7.x, inclusive.
1157+
for ver in [v(26, 0, 0), v(26, 2, 0), v(26, 7, 0)] {
11451158
assert!(
11461159
!source_maps_safe(&ver),
11471160
"source maps must be withheld on {ver:?}"

‎crates/nub-core/src/node/version.rs‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,6 @@ impl NodeVersion {
2020
pub(crate) fn major(&self) -> u64 {
2121
self.0.major
2222
}
23-
pub(crate) fn minor(&self) -> u64 {
24-
self.0.minor
25-
}
2623

2724
/// The minimum Node version Nub supports at all. Below this, Nub
2825
/// hard-errors before spawning — the user must upgrade Node or run

‎site/content/docs/runtime/typescript.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,4 +130,4 @@ Error: kaboom
130130

131131
The stack frame reports `app.ts:2:8` — the line in your source, not the transpiled output. To turn it off, pass `--no-enable-source-maps`.
132132

133-
Source maps are injected on every supported Node version except the **26.2.x** patch band, where a Node regression makes a no-message `assert(false)` rethrow as a `TypeError` instead of an `AssertionError` when source maps are on. On 26.2.x Nub withholds the flag, so stack traces there are not remapped. Every other version (18.19 through 26.1, and 26.3+) gets source maps.
133+
Source maps are injected on every supported Node version except **26.0 through 26.7**, where a Node regression ([nodejs/node#63169](https://github.com/nodejs/node/issues/63169)) makes a no-message `assert(false)` throw a `TypeError` instead of an `AssertionError` when source maps are on. Nub withholds the flag across that band, so stack traces are not remapped there. Every other version gets source maps: 18.19 through 25.x, and 26.8 onward, where the upstream fix ships.

‎wiki/research/nub-v0.5-augmentation-regressions.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,13 @@ One `typeof` probe against a lazy undici-backed global pulls 227 modules into ev
3939

4040
### Cause 2 — `--enable-source-maps` always injected
4141

42-
Injecting the flag on every run puts each invocation on Node's source-map error path, which changes what a message-less assertion throws. Accepted as-is.
42+
Injecting the flag on every run puts each invocation on Node's source-map error path, which changes what a message-less assertion throws. Gated off across the affected Node 26 band (see the reversed verdict below).
4343

4444
- **Tests:** ~5 (assert ×2, source-map-enable, es-module-cjs-named-error; also the 26.x TypeError).
4545
- **What breaks:** nub injects `--enable-source-maps` on every run (`flags.rs`, `ALWAYS_INJECT`). Node's error path bails when a file has no source map, so (a) on Node 26 a no-message `assert.ok(false)` throws **`TypeError` instead of `AssertionError`** — breaks `catch (e) { e instanceof assert.AssertionError }`; (b) on Node 24.9–25.x the assert *message* degrades from the source expression to `false == true`; (c) a child spawned without the flag still gets remapped stacks.
46-
- **Landed:** source-maps injection predates the June benchmark — the 26.2 gate for it is from **2026-06-11**, so the behavior is **old / pre-existing**, not part of recent growth. The 26.x TypeError only became visible as Node 26 shipped and became the recommended line.
47-
- **VERDICT — accept, no fix (2026-07-24).** The bug is narrow: only a bare `assert.ok(false)`/`assert(false)` with **no message** (asserts with a message, `strictEqual`, and plain throws are all fine). A 26.x-wide gate was briefly landed then **dropped** — disabling TS stack-trace remapping for every Node-26 user to fix that one edge case, whose workaround is passing a message, was the wrong trade. Not documented, not filed upstream, by decision. The `source_maps_safe` gate stays as-is (26.2-only, unrelated).
46+
- **Landed:** source-maps injection predates the June benchmark — the original 26.2-only gate for it is from **2026-06-11**, so the behavior is **old / pre-existing**, not part of recent growth. The 26.x TypeError only became visible as Node 26 shipped and became the recommended line.
47+
- **VERDICT — REVERSED 2026-08-21: gate the whole released 26.x band.** The 2026-07-24 call below accepted the divergence and left `source_maps_safe` at 26.2-only. Two facts overturned it. First, the band was mis-scoped: the regression is [nodejs/node#63169](https://github.com/nodejs/node/issues/63169) and it affects **every released 26.x** — reproduced on 26.0.0, 26.3.0, 26.5.1 and 26.7.0 — so a 26.2-only gate protected almost nobody while the docs claimed 26.1 and 26.3+ were clean. Second, the failure is a wrong error TYPE, not a degraded message, so it breaks `node:test` and any `instanceof assert.AssertionError` check from outside the assertion, where "pass a message" is not a workaround the caller owns. Upstream fixed it on `main` in b5d37cd4 ([nodejs/node#63215](https://github.com/nodejs/node/pull/63215), 2026-08-20), unreleased as of v26.7.0. `source_maps_safe` now withholds the flag for `26.0.0 <= v < 26.8.0` as a stopgap; re-verify when 26.8.0 ships. 25.x is clean (25.9.0 throws an `AssertionError` with the degraded `false == true` message — right type, worse text).
48+
- **Superseded verdict — accept, no fix (2026-07-24).** The bug was judged narrow: only a bare `assert.ok(false)`/`assert(false)` with **no message** (asserts with a message, `strictEqual`, and plain throws are all fine). A 26.x-wide gate was briefly landed then **dropped**, on the reasoning that disabling TS stack-trace remapping for every Node-26 user to fix one edge case was the wrong trade. That reasoning rested on the mis-scoped band and on treating the type corruption as cosmetic.
4849

4950
### Cause 3 — Default `NODE_COMPILE_CACHE` lacks provenance
5051

@@ -131,3 +132,4 @@ That left zero automated compat signal for the whole June→July window in which
131132
Every revision to this document, with the date and what changed.
132133

133134
- 2026-07-24 — Initial write-up. 70 regressions → 9 root causes with git provenance. Key finding: none introduced by/since the benchmark; all landed 2026-06-03…07-09 during v0.1→v0.5 development; causes 2/3/4/9b predate the June benchmark, the rest are the 53→70 growth. Disambiguated the 07-23 fix "revert" (an editor discard) from code regressions.
135+
- 2026-08-21 — **REVERSAL** on Cause 2. The `--enable-source-maps` regression band was mis-scoped as 26.2-only; it is [nodejs/node#63169](https://github.com/nodejs/node/issues/63169) and covers every released 26.x (reproduced on 26.0.0 / 26.3.0 / 26.5.1 / 26.7.0). The 2026-07-24 "accept, no fix" verdict is superseded: `source_maps_safe` now withholds the flag for `26.0.0 <= v < 26.8.0`, pending the upstream fix b5d37cd4 ([nodejs/node#63215](https://github.com/nodejs/node/pull/63215)) reaching a release.

0 commit comments

Comments
 (0)