Skip to content

[cli] Fix server stack traces pointing at the wrong source on Node 24.22+ - #52102

Merged
kitten merged 2 commits into
mainfrom
@brent/cli-loader-sourcemap
Oct 27, 2026
Merged

kitten merged 2 commits into
mainfrom
@brent/cli-loader-sourcemap

Conversation

@brentvatne

@brentvatne brentvatne commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

Why

Server stack traces in dev point at the wrong source on Node 24.22+ (start-server-stack-traces.test.ts fails on jest-ubuntu (1) whenever the runner gets 24.22.x):

  1. Node 24.22 reads source maps lazily, after @expo/require-utils has deleted the temp map file.
  2. Loader bundle URLs don't carry isLoaderBundle, so Metro's /symbolicate fallback rebuilds the full bundle and maps frames against it.

How

  • load.ts: call findSourceMap() before deleting the map file.
  • metroOptions.ts: add transform.isLoaderBundle=true to loader bundle URLs.

Test Plan

  • start-server-stack-traces.test.ts on Node 24.22.1: 4/4 fail before, 4/4 pass after.
  • New metroOptions unit test for the loader bundle URL.

🤖 Generated with Claude Code

….22+

`@expo/require-utils` writes each server bundle's source map to a temporary
file and removes it right after `_compile`, assuming Node parses the map
eagerly. Since Node 24.22.0, Node only records the map's path during
`_compile` and reads the file on the first lookup, after it's gone, so no
server bundle (API routes, rendering, data loaders) has a Node-level source
map. Look the map up before removing the file.

Frames Node can't map fall back to Metro's /symbolicate, which rebuilds the
bundle from the frame's URL. A data loader bundle's URL matched its entry's
full bundle, so Metro mapped loader errors against the full bundle and
pointed them into react/jsx-runtime.js. Mark loader bundles with
`transform.isLoaderBundle` in their URL.

This is why `start-server-stack-traces.test.ts` failed on every CI run that
got Node 24.22.x and passed on every run that got 24.21.0.
@expo-bot expo-bot added the contributor: internal PR author is a member, owner, or collaborator of the expo org label Oct 22, 2026
@brentvatne
brentvatne requested a review from kitten October 22, 2026 21:53
@expo-bot expo-bot added Platform: web Using Expo in the browser sdk-58 labels Oct 22, 2026
@expo-bot

Copy link
Copy Markdown
Collaborator

Bug fix · 80% confidence

Preliminary assessment based on the supplied report; claims have not been verified.

  • Impact: Aims to make dev server stack traces (API routes, rendering, data loaders) map back to the original source instead of the wrong module.
  • Scope: The author reports the source-map loss on Node 24.22.0 and 24.22.1. The loader-bundle URL mismatch does not depend on the Node version.
  • Platforms: Web
  • Labels: sdk-58, Platform: web

@expo-bot expo-bot added the bot: passed checks ExpoBot has nothing to complain about label Oct 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Subscribed to pull request

File Patterns Mentions
packages/@expo/cli/** @byCedric, @kitten
packages/@expo/require-utils/** @kitten

Generated by CodeMention

@brentvatne

Copy link
Copy Markdown
Member Author

@expo-bot verify

@expo-bot

Copy link
Copy Markdown
Collaborator

Outcome: pass

@brentvatne Result: reproduced and confirmed. On base 651db16, the e2e test "maps server data loader errors to the original source" fails on Node 24.22.1 (4/4) and Node 26.12.1 (2/2). It passes on Node 24.21.0 (3/3). On PR head 4fe63891, it passes on all three versions (4/4, 3/3, 2/2). Both causes in the PR description are correct. Each change alone also makes the e2e test pass on Node 24.22.1 (load.ts only: 3/3; metroOptions.ts only: 6/6).

Reporter: Nothing is needed from you. The Node regression is wider than the PR says. Node's changelog puts the same change in Node 26.9.0, and Node 26.12.1 also loses the source map in my test. You can add that to the Why section.

Maintainer: The PR is correct as written. Unit tests, typecheck, and lint pass. The new metroOptions test fails on base and passes with the change. Two calls are yours. (1) AGENTS.md asks for one published package per PR. This PR changes @expo/require-utils and @expo/cli, and each change fixes a different cause, so a split is possible. (2) On Node 24.22.1 the eager findSourceMap adds about 35 ms per load for a 2 MB map. Node 24.21.0 already has that cost.

Environment and versions
  • E2B Linux sandbox, 4 vCPU, 3.9 GB. No simulator: this is a CLI and Node runtime change. No EAS builds.
  • Repository: base 651db16bdc7fdc138b31fbc666ff688153f8ae21 and PR head 4fe63891d75c698bbc214ffad032c701a2a03d0f (the exact headRefOid), fetched shallow. pnpm install with pnpm 12.2.1 (full install with prepare).
  • Node binaries from nodejs.org: 22.22.0, 24.21.0, 24.22.0, 24.22.1, 26.12.1. The e2e test runs with that node first on PATH, so the spawned expo start uses the same version.
  • The PR diff header says the diff is complete (87 of 87 lines). git diff base..head also shows .github/workflows/* changes. Those come from base commit [ci] Run the CLI and SDK Windows jobs on GitHub runners, and check-packages on 16 vCPU #52100, which the PR branch does not contain. They do not affect these tests.
E2E tally: start-server-stack-traces.test.ts

Command: npx jest --config e2e/jest.config.js e2e/__tests__/start-server-stack-traces.test.ts in packages/@expo/cli, after rebuilding @expo/require-utils and @expo/cli (build:cli) for each arm.

Tree Node API route test Loader test
base 651db16 24.21.0 3/3 pass 3/3 pass
base 651db16 24.22.1 4/4 pass 0/4 pass
base 651db16 26.12.1 2/2 pass 0/2 pass
PR head 4fe63891 24.21.0 3/3 pass 3/3 pass
PR head 4fe63891 24.22.1 4/4 pass 4/4 pass
PR head 4fe63891 26.12.1 2/2 pass 2/2 pass
head, metroOptions.ts reverted to base (only load.ts change) 24.22.1 3/3 pass 3/3 pass
head, load.ts reverted to base (only metroOptions.ts change) 24.22.1 6/6 pass 6/6 pass

For each single-change arm, I checked the built output before the runs:

  • load.ts only: git status shows only metroOptions.ts reverted to base. build/src/.../metroOptions.js has 0 transform.isLoaderBundle lines. build/load.js has 1 findSourceMap line.
  • metroOptions.ts only: git diff 651db16 -- load.ts metroOptions.ts shows only metroOptions.ts | 8 ++++++++. require-utils build exit 0, cli build exit 0. findSourceMap in build/load.js: 0. transform.isLoaderBundle in build metroOptions.js: 1. Two series of 3 runs each, all pass.

The base failure on Node 24.22.1 is the same failure the PR describes. The loader frame maps into react/jsx-runtime.js:

Metro error: Thrown from a loader
Code: jsx-runtime.js
> 4 |   module.exports = require('./cjs/react-jsx-runtime.production.js');
Call Stack
  <global> (../../node_modules/.pnpm/react@19.3.0/node_modules/react/jsx-runtime.js:4)
  <global> (../../node_modules/.pnpm/react@19.3.0/node_modules/react/jsx-runtime.js:7)
  acc.<computed> [as loader] (../../packages/@expo/cli/build/src/start/server/getStaticRenderFunctions.js:147:33)
Cause 1: Node 24.22+ reads the source map file after it is removed

compileModule writes the map to a temporary file, compiles the module, then deletes the file in finally. The comment on line 233 says Node parses the map during _compile. Node's changelog lists "lib: defer source map payload decoding until first use" (nodejs/node#65490) in 24.22.0 and 26.9.0. After that change, the first findSourceMap runs after the file is gone and returns undefined.

Harness: the published @expo/require-utils@58.0.4 build/load.js (identical to the build from base, whitespace aside) and a copy with the PR's findSourceMap lines inserted at the same place. The harness calls the real evalModule with a Babel source map, throws from the module, and reads error.stack.

Node base: map after unlink base: stack mapped PR: map after unlink PR: stack mapped
22.22.0 found yes found yes
24.21.0 found yes found yes
24.22.0 missing no found yes
24.22.1 missing no found yes
26.12.1 missing no found yes

Base on 24.22.1 prints at fail (/home/user/h/app/loader-error.tsx.bundle?platform=web&...:7:9). The PR copy prints the original position loader-error.tsx:4:9.

The PR calls findSourceMap before it restores the source map state. Node's findSourceMap skips paths under node_modules when nodeModules support is off. Because of this order, the PR call also loads the map for a bundle whose path is under node_modules.

Cause 2: loader bundle URL is the same as the full bundle URL

createBundleUrlSearchParams does not read isLoaderBundle. getMetroDirectBundleOptions does put it in customTransformOptions. So the loader bundle is a 1-module graph, but metroLoadModuleContents gives it the same filename as the full route bundle. When Node does not map a frame, the Metro symbolication fallback rebuilds the bundle from that filename and gets the full bundle. The loader line numbers then land in react/jsx-runtime.js.

The new unit test fails on base metroOptions.ts and passes with the change:

✕ distinguishes a loader bundle from the full bundle of the same entry
Expected: not "/app/index.bundle?platform=web&dev=true&hot=false&resolver.environment=node&transform.environment=node"

Other uses of the filename: evalMetroNoHandling passes cache: false, so require.cache does not use the filename. The loader path calls ssrLoadModule without extras.hot, so the SSR HMR URL is not built from it. With the change, the loader bundle and the full bundle also get separate entries in Node's source map cache. On base they share one key.

Why both changes are useful

Each change alone makes the e2e test pass on Node 24.22.1. They fix different layers:

  • load.ts restores the Node-level source map. Without it, error.stack that app code reads (for example in an API route or a logging service) is unmapped on Node 24.22+ and 26.9+. The terminal output is mapped only because of the Metro fallback.
  • metroOptions.ts makes the Metro fallback use the correct bundle. It applies when Node cannot map a frame on any Node version.
Repository checks run on PR head 4fe6389
  • @expo/require-utils: pnpm test 6 suites, 134 tests pass. pnpm run typecheck clean. pnpm run lint 0 warnings, 0 errors.
  • @expo/cli: npx jest src/start/server: Test Suites: 73 passed, 73 total, Tests: 896 passed, 896 total. pnpm run typecheck exit 0. oxlint on src/start/server/middleware 0 warnings, 0 errors.
  • I did not run et check-packages, because the sandbox has no direnv/et setup. The commands above are the package scripts it runs.
Load-time cost of the eager findSourceMap call

The harness ran evalModule 5 times for each arm, on react-dom-client.development.js passed through Babel (923 KB code, 2067 KB map). Times are ms for each call, three series for each cell:

Node base PR
24.21.0 68 88 50 51 50 / 58 75 53 59 55 / 58 52 73 50 50 60 53 98 74 73 / 73 85 54 51 52 / 58 50 79 51 51
24.22.1 21 17 17 18 18 / 22 18 17 17 17 / 21 17 18 17 19 53 52 74 49 49 / 54 73 49 54 57 / 52 76 48 56 56

Raw output of one series: {"node":"v24.22.1","arm":"base","codeKB":923,"mapKB":2067,"ms":[21,17,18,17,19]} and {"node":"v24.22.1","arm":"patched","codeKB":923,"mapKB":2067,"ms":[52,76,48,56,56]}.

On Node 24.21.0 there is no measurable difference. On Node 24.22.1 the PR adds about 35 ms for each compile of this map. This is the cost that Node 24.21.0 already has. This is a single-machine measurement with noise.

Not covered
  • Windows and macOS. I did not run the e2e test on those platforms. The load.ts change runs on all platforms.
  • ESM (format.mode module) server bundles. The harness and the e2e test use the CommonJS path.
  • Bun. compileModule skips the source map path when process.isBun is set, so the change does not apply there.
  • I did not open lib: defer source map payload decoding until first use nodejs/node#65490. I read its entry in Node's CHANGELOG_V24.md and CHANGELOG_V26.md.

Co-authored-by: Phil Pluckthun <phil@kitten.sh>
@kitten
kitten merged commit 657ec93 into main Oct 27, 2026
30 of 32 checks passed
@kitten
kitten deleted the @brent/cli-loader-sourcemap branch October 27, 2026 20:10
kitten added a commit that referenced this pull request Oct 27, 2026
….22+ (#52102)

# Why

Server stack traces in dev point at the wrong source on Node 24.22+
(`start-server-stack-traces.test.ts` fails on `jest-ubuntu (1)` whenever
the runner gets 24.22.x):

1. Node 24.22 reads source maps lazily, after `@expo/require-utils` has
deleted the temp map file.
2. Loader bundle URLs don't carry `isLoaderBundle`, so Metro's
`/symbolicate` fallback rebuilds the full bundle and maps frames against
it.

# How

- `load.ts`: call `findSourceMap()` before deleting the map file.
- `metroOptions.ts`: add `transform.isLoaderBundle=true` to loader
bundle URLs.

# Test Plan

- `start-server-stack-traces.test.ts` on Node 24.22.1: 4/4 fail before,
4/4 pass after.
- New `metroOptions` unit test for the loader bundle URL.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Phil Pluckthun <phil@kitten.sh>
kitten added a commit that referenced this pull request Oct 28, 2026
….22+ (#52102)

Server stack traces in dev point at the wrong source on Node 24.22+
(`start-server-stack-traces.test.ts` fails on `jest-ubuntu (1)` whenever
the runner gets 24.22.x):

1. Node 24.22 reads source maps lazily, after `@expo/require-utils` has
deleted the temp map file.
2. Loader bundle URLs don't carry `isLoaderBundle`, so Metro's
`/symbolicate` fallback rebuilds the full bundle and maps frames against
it.

- `load.ts`: call `findSourceMap()` before deleting the map file.
- `metroOptions.ts`: add `transform.isLoaderBundle=true` to loader
bundle URLs.

- `start-server-stack-traces.test.ts` on Node 24.22.1: 4/4 fail before,
4/4 pass after.
- New `metroOptions` unit test for the loader bundle URL.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Phil Pluckthun <phil@kitten.sh>
@kitten kitten added the sdk-57 label Oct 28, 2026
kitten added a commit that referenced this pull request Oct 28, 2026
….22+ (#52102)

Server stack traces in dev point at the wrong source on Node 24.22+
(`start-server-stack-traces.test.ts` fails on `jest-ubuntu (1)` whenever
the runner gets 24.22.x):

1. Node 24.22 reads source maps lazily, after `@expo/require-utils` has
deleted the temp map file.
2. Loader bundle URLs don't carry `isLoaderBundle`, so Metro's
`/symbolicate` fallback rebuilds the full bundle and maps frames against
it.

- `load.ts`: call `findSourceMap()` before deleting the map file.
- `metroOptions.ts`: add `transform.isLoaderBundle=true` to loader
bundle URLs.

- `start-server-stack-traces.test.ts` on Node 24.22.1: 4/4 fail before,
4/4 pass after.
- New `metroOptions` unit test for the loader bundle URL.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Phil Pluckthun <phil@kitten.sh>
@kitten kitten added the sdk-56 label Oct 28, 2026
@alanjhughes alanjhughes added the published Changes from the PR have been published to npm label Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bot: passed checks ExpoBot has nothing to complain about contributor: internal PR author is a member, owner, or collaborator of the expo org Platform: web Using Expo in the browser published Changes from the PR have been published to npm sdk-56 sdk-57 sdk-58

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants