Next.js standalone: deferred-require binding captured by-value (as unresolved thunk) by a class constructor → 'undefined is not a constructor'

[proggeramlug]

Summary

Compiling a Next.js 16 standalone app-router server with Perry produces HTTP 500 (TypeError: undefined is not a constructor) where node server.js returns 200. Root cause: a deferred/adopted require whose binding is captured by value by a class constructor before the required module resolves — so the constructor sees the unresolved thunk (a closure) instead of the module object.

Concretely, in app-page-turbo.runtime.prod.js:

let uw = require("next/dist/server/lib/incremental-cache/shared-cache-controls.external.js");
class IncrementalCache {
  constructor(...) { /* ... */ this.cacheControls = new uw.SharedCacheControls(this.prerenderManifest); }
}

uw resolves to the correct object everywhere it's read via the imported-var getter, but the IncrementalCache constructor reads a by-value capture of uw taken at class-definition time — when shared-cache-controls (a deferred module) hasn't initialized yet, so uw is still its unresolved thunk/closure. Thus uw.SharedCacheControls === undefined → new undefined(...).

Reproduction (self-contained, deterministic)

Not minimally reproducible in isolation — see "Why no minimal repro" below. This full-bundle repro is deterministic.

# 1. Generate the app (Next 16.2.9, React 19.2.4)
npx create-next-app@16.2.9 perry-nextjs-demo --ts --app --no-src-dir --no-tailwind --no-eslint --import-alias "@/*"
cd perry-nextjs-demo
# 2. Enable standalone output
cat > next.config.ts <<'CFG'
import type { NextConfig } from "next";
const nextConfig: NextConfig = { output: "standalone" };
export default nextConfig;
CFG
# 3. Build
npx next build
# 4. Compile the standalone server with Perry
cd .next/standalone/perry-nextjs-demo
PERRY_DEBUG_SYMBOLS=1 PERRY_LL_O0_THRESHOLD_BYTES=536870912 \
  PERRY_ALLOW_PERRY_FEATURES=1 PERRY_ALLOW_EVAL=1 PERRY_ALLOW_UNIMPLEMENTED=1 \
  perry compile server.js -o server-native --no-cache
# 5. Run + request
PORT=3000 ./server-native &
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/     # Perry: 500   |   node server.js: 200

The 500 originates at IncrementalCache's new uw.SharedCacheControls(...) (visible by patching base-server.js's logError to print err.stack).

Root cause (verified)

Value-flow trace (runtime is_closure probes), single run:

• shared-cache-controls's default export — module-global store = OBJECT (is_closure=false).
• The importer's getter-call result (the value assigned to uw) = the SAME OBJECT (identical NaN-box bits, is_closure=false).
• But the IncrementalCache constructor's captured uw = a FUNCTION (anonymous closure).
• A capture-site probe found 47 by-value captures-of-closures in app-page-turbo; uw is one of them.

Why the boxing analysis misses it — crates/perry-codegen/src/boxed_vars.rs (collect_boxed_vars_scope):

boxed = (declared AND captured AND mutated) OR self-recursive-closure   (minus for-loop init)

uw is captured but assigned once (not "mutated"), so it's snapshotted by value (js_closure_get_capture_f64, non-boxed; read at expr/literals_vars.rs). The existing self-recursive-closure rule (collect_self_recursive_closure_ids) is the exact precedent — it boxes let f = closure() precisely because "the store happens after captures populate." uw's deferred require is the same "value not ready at capture" shape, just with a require/import init instead of a closure init.

cjs_wrap rewrites const uw = require('S') into an adopted import (is_deferred_require on the import decl); the require is function-local (inside the cjs-wrap IIFE), so shared-cache-controls does not chain into app-page-turbo's eager init and resolves lazily — after class IncrementalCache is defined and uw is captured.

Ruled out (exhaustively)

module-prefix symbol collision (0), within-module global-id collision (0), FuncId collision (0), -O3 optimization (W6 persists at -O0), GC move (persists with PERRY_GEN_GC=0), and the IIFE return value itself (the IIFE returns the correct object). The defect is specifically the by-value capture of a not-yet-resolved deferred-require binding.

Candidate fixes

1. Box-when-captured for adopted-require/import bindings captured by a closure (mirror the self-recursive-closure rule) so the capture is by-reference and sees the resolved value. (Confirm the box receives the resolved value, not just the thunk.)
2. Eager-init: a cjs-wrap-IIFE require runs at module init — resolve it into the local before the class definition, so the by-value capture is the object.
3. Getter-on-read: lower the constructor's uw read through the imported-var getter (perry_fn_<src>__<origin>), consistent with init-scope reads, instead of a by-value capture.

The correct site depends on whether uw is a Stmt::Let (boxed_vars-visible) or a pure adopted-import binding — worth confirming first.

Why no minimal repro (yet)

Four documented attempts all pass (return the object): (a) module-level require read from a class constructor; (b) IIFE-captured require read from a class constructor; (c) compilePackage module.exports = /regex/ patterns; (d) cross-module compilePackage cjs const uw = require('dep'); module.exports.C = class { constructor(){ new uw.Thing() } }. In small graphs the required module initializes before the capturing class is defined, so the by-value snapshot is already the object. The bug needs the bundle's deferred-load order (the required module initializes after the class definition). A faithful minimal repro likely requires forcing that order (a deferred/lazy module that resolves after the capturing class is defined).

Context

6th wall in the Next.js app-router bring-up. Walls 1–5 are fixed on feat/nextjs-wall-46 (0-arg class-object resolve, readFileSync ENOENT, anon-class-expression capture, native-module shadowing, primitive-index SIGSEGV, etc.); with this fixed, render should advance past IncrementalCache construction.

[proggeramlug]

Refined diagnosis (validated against the live standalone bundle)

Reproduced on current main (post-#5438): curl localhost:PORT/ → HTTP 500, server logs TypeError: undefined is not a constructor (the new uw.SharedCacheControls(this.prerenderManifest) in IncrementalCache).

Instrumented the codegen at the Expr::NewDynamic site. There are 5 new <x>.SharedCacheControls sites in the bundle, and they split:

• 1 works — x lowers as ExternFuncRef → the import getter perry_fn_<src>__<name>() (which fires <S>__init() for _lazyreq_) → the real module object.
• 4 fail — x lowers as LocalGet(id) with captured=false, local=true, name=None. By codegen time the closure-conversion has already materialized the captured uw into a nameless __perry_cap_N parameter holding the snapshot taken at closure-creation (class-definition time) — which, for the deferred require(".../shared-cache-controls.external.js"), is the unresolved thunk. thunk.SharedCacheControls → undefined.

Why a localized codegen fix doesn't work

A natural fix — "when a LocalGet is an imported var, resolve through its getter instead of the captured snapshot" — cannot fire here: the var is no longer a live capture (captured=false) and the materialized __perry_cap_ param has no name (local_id_to_name is per-function and only populated by let stmts), so codegen can't identify it as the import. Confirmed empirically: such a branch logged 0 hits on the bundle.

Root: inconsistent require-adoption

is_adopted_require (collect_modules.rs:1563) only tags requires already promoted into hir_module.imports. The 1 working site's uw was promoted (→ ExternFuncRef, getter+__init, live binding). The 4 failing uw = require(shared-cache-controls) were not promoted — they stayed as local require-Lets, got captured into nested constructors, and were materialized to __perry_cap_ snapshot params taken before the source module initialized (the deferred load order #5437 describes).

Candidate fix layers (each needs full-bundle validation; broad blast radius)

1. collect_modules / cjs_wrap — promote const x = require(S) to an adopted import consistently across all sites (so every reference resolves as ExternFuncRef + getter, like the 1 working site). Risk: the deferred load order exists to avoid eager-init cycles.
2. closure-conversion (perry-transform/closure.rs) — don't materialize imported/adopted-require captures into snapshot __perry_cap_ params; leave them as ExternFuncRef re-resolved in the nested function (the import identity is still known at this layer; it's lost by codegen).
3. deferred-require resolution — make the captured snapshot lazy: resolve (fire <S>__init() + read the namespace) at read-time rather than capturing the pre-init value.

Layer 2 is the most surgical and keeps the live-binding semantics; it's where the import identity is still available.

[proggeramlug]

Root cause pinned to a single divergence + concrete fix recipe

Traced the resolution end-to-end. The 5 new uw.SharedCacheControls sites split by how const uw = require("…/shared-cache-controls.external.js") is bound, decided in crates/perry-hir/src/lower/lower_expr.rs Ident resolution (≈643–678):

1. ctx.lookup_local("uw") is Some → LocalGet(uw_id) → captured into the class as a __perry_cap_N snapshot (taken at class-definition, before the deferred module initialized → unresolved thunk). ← the 4 failing sites
2. binding absent → falls through to ExternFuncRef("uw") → the import getter perry_fn_<src>__<name>() (fires __init, returns the real module). ← the 1 working site

Why the binding is present for the 4: register_require_namespace_binding (destructuring/var_decl.rs:818, gated on require_resolvable_native_specifier) only removes the local + installs a namespace binding for native/Node-builtin requires (fs/path/crypto/…). shared-cache-controls.external.js is a compiled user module, so the gate returns None, the local let is kept, and the class captures the snapshot. The 1 working site was adopted into hir_module.imports via a different path (cjs_wrap promotion), so it never had a local.

Why layer-2 (closure-conversion) alone is insufficient: rewriting the captured LocalGet → ExternFuncRef("uw") only resolves if uw is registered as an import with a getter (import_function_prefixes). For the non-adopted modules it isn't — so the rewrite would still yield undefined. The getter must exist first.

Fix recipe (the real change): extend the var_decl.rs:818 gate so const x = require(S) installs a require-namespace binding (no kept local; reads resolve via the module getter) when S is any module in the compile graph — not only native specifiers. shared-cache-controls already has a getter (the 1 working site uses it), so all 5 sites would then resolve identically to the real object. Equivalent alternative: make cjs_wrap's require→import adoption consistent across all copies.

Blast radius / why this needs a dedicated, fully-validated change: it flips every const x = require(userModule) from a kept-local to a namespace binding. That requires compiled-module awareness at lowering time and a full cargo test + bundle re-validation, since other modules may depend on the kept-local behavior. It is not a safe single-pass edit.

Validated against the live standalone bundle throughout (HTTP 500 → undefined is not a constructor; instrumented Expr::NewDynamic showed the 4× LocalGet captured=false local=true name=None vs 1× ExternFuncRef).

[proggeramlug]

Validated against the live standalone bundle: PR #5447 (lower static literal require in user modules) clears W6. With #5447 the new uw.SharedCacheControls(...) undefined is not a constructor is gone (error count 0 vs 18 on main) — promoting the static-literal const uw = require(".../shared-cache-controls.external.js") into the import graph makes uw resolve through the module getter exactly as the root-cause analysis above predicted. The render now advances to the next wall (server boot: TypeError: getStore is not a function + the Date class-extension warning → HTTP 000). Recommend closing this as fixed-by #5447 once it merges.

[proggeramlug]

Fixed by #5447 (landed as 87f9a44 on main). Static-literal require(...) in user modules now lowers into the import graph, so const uw = require(".../shared-cache-controls.external.js") resolves via the module getter instead of a captured pre-init snapshot — new uw.SharedCacheControls(...) no longer throws (bundle error count 18 → 0). Next wall is separate (server boot: getStore is not a function); will track that independently.

[proggeramlug]

Reopening — W6 is not actually fixed. My earlier 'PR #5447 clears W6 (error count 18→0)' was an artifact: that build crashed at the getStore boot wall (HTTP 000) before handling any request, so the request-time new uw.SharedCacheControls was never reached (0 = not executed, not fixed).

On current main (87f9a44, includes #5447) the getStore boot crash is gone (other main commits), so the server boots and the request now reaches the site — and new uw.SharedCacheControls still throws undefined is not a constructor (confirmed 13× via instrumented js_new_function_construct, callee .SharedCacheControls).

#5447 made partial progress (the error shape implies uw now resolves to a namespace object rather than a thunk), but SharedCacheControls is undefined on that namespace — the export resolution for require("next/dist/server/lib/incremental-cache/shared-cache-controls.external.js") is incomplete. Continuing the real fix; the CHANGELOG 'clears W6' line for v0.5.1193 is inaccurate and should be corrected.

[proggeramlug]

Root cause fully pinned (supersedes the earlier capture/thunk hypothesis)

With the getStore boot crash fixed (other main commits), the server now boots and binds, so the request path runs and reaches new uw.SharedCacheControls. Instrumented end-to-end on current main (87f9a44, includes #5447):

1. The throw is js_new_function_construct(undefined) at new uw.SharedCacheControls — and crucially the error shape is the object-missing-property kind (Perry's new o.Missing() → "undefined is not a constructor", vs new undefined.x → "Cannot read properties of undefined"). So uw is a real object, not undefined.
2. A JS-level probe (Object.keys(uw) injected at the site) prints keys=[] scc=undefined esm=undefined — uw is an empty exports object.
3. uw lowers as LocalGet (runtime require), not ExternFuncRef — so feat(compile): lower static literal require in user modules #5447's transform did not convert this require into an import edge.
4. Yet shared-cache-controls.external.js is compiled — its object file is in the 714-module graph (node_modules_next_dist_server_lib_incremental_cache_shared_cache_controls_external_js.o).

Conclusion: the module is compiled, but the runtime require("next/dist/.../shared-cache-controls.external.js") (issued from inside a webpack factory function) returns an empty exports object — it isn't connected to the compiled module, so the module body (incl. Object.defineProperty(exports, "SharedCacheControls", {get})) never runs. The earlier "captured thunk" framing was wrong: uw IS the exports object (a captured reference is fine — defineProperty mutates it in place); the real bug is the exports never get populated because the compiled module's init doesn't fire for this require.

This is a class of failures — the same probe surfaced NonRecordingSpan (OpenTelemetry) and other new <ns>.<Class> sites failing identically.

Note: #5447's should_leave_runtime_require actually returns false for this specifier (next ∈ compilePackages), so it's eligible — but #5447 hoists top-level const x = require(...) to imports; this require is inside a webpack module-factory function, so it stays a runtime require.

Fix design (module-loading architecture — substantial, broad blast radius)

Connect a factory-internal runtime require(spec) of an already-compiled compilePackages module to that module: fire its <module>__init() and return its populated exports namespace, rather than a fresh empty object. Two avenues:

• Extend feat(compile): lower static literal require in user modules #5447's static_require_transform to also lower non-top-level literal requires of compiled packages (harder — can't simply hoist a factory-scoped require to a top-level import), or
• Make the runtime require resolver (js_module_ambient_require / the require path) map a compiled-module specifier → that module's init+exports (a runtime registry keyed by resolved specifier).

Either touches how every factory-internal/runtime require of a compiled module resolves, so it needs careful design + full validation. Coordinating with #5447's author (@JagritGumber) is sensible since it's adjacent to that transform.

[proggeramlug]

Fix now scoped to one specific thing (instrumented the path registry)

Building on the previous comment (uw = empty exports of a compiled, registered module), I instrumented Perry's path-module registry (js_register_path_module / js_require_path_module):

• W8-REG fires — shared-cache-controls.external.js runs its init eagerly and self-registers its populated exports under its absolute path (…/node_modules/next/dist/server/lib/incremental-cache/shared-cache-controls.external.js). So the real exports object (with the SharedCacheControls getter) exists in MODULE_PATH_REGISTRY.
• W8-LOOKUP never fires — the bundle's require("next/dist/.../shared-cache-controls.external.js") never consults the registry.

Why: the require is resolved by the cjs_wrap static require_cases (wrap.rs:341), which emits if (specifier === '<spec>') return <local>; — i.e. it returns the cjs-adopted import namespace <local> and returns before the js_require_path_module fallback. For this module <local> is empty (the populated runtime exports live in the path registry, not in that adopted-import namespace).

Confirmed contrast: a minimal const uw = require("./m") where m uses the identical Object.defineProperty(exports, "X", {get}) shape works — because #5447 routes it through import * as (populated). The bundle's require is shadowed (webpack factory param), so it hits the cjs_wrap static case → empty <local>.

Fix (scoped, but needs cjs_wrap plumbing)

Make the cjs require resolve to the module's runtime exports (already populated in the path registry) rather than the empty adopted-import namespace. Options:

1. In the require_cases codegen, for a spec that resolves to a cjs-wrapped/compiled module, emit a registry route (return __perry_require_path_module('<resolved-abs-path>')) instead of (or as a non-empty-preferring fallback to) return <local>. Needs the resolved absolute path per require_spec threaded into wrap.rs.
2. Or fix the adopted-import namespace itself to reflect the module's runtime module.exports for cjs modules whose exports are dynamic (defineProperty-based), so <local> is populated.

Either is a focused, real change with validation surface (the server boots now, so it's end-to-end verifiable). Adjacent to #5447 — coordinating with @JagritGumber is sensible.

[proggeramlug]

Implementation attempt: wrong layer (recorded so the next attempt skips it)

Tried fixing this at the cjs require shim: (a) added package-relative suffix resolution to js_require_path_module, and (b) changed cjs_wrap's static require_cases to consult the path registry when the adopted-import namespace is empty.

It did not land — instrumentation (FIX-LOOKUP) shows the bundle's require("next/dist/.../shared-cache-controls.external.js") never reaches js_require_path_module / the cjs require shim at all (count 0). Combined with uw lowering as LocalGet (not an ExternFuncRef import getter, and not a runtime shim call), the require is resolved at HIR-lowering into an empty adopted/static namespace — the shim and path registry are never consulted for it.

So the fix is NOT in js_require_path_module / require_cases. It's in the import-namespace resolution layer: import <x> from "<cjs-module-with-defineProperty-exports>" (the adopted form for let uw = require(spec)) must resolve <x> to the module's runtime module.exports (which is correctly populated and path-registered at init), not a static-export-derived namespace that's empty for dynamic (Object.defineProperty(exports, …)) CJS exports.

Reverted both speculative changes (didn't fix it, shouldn't land untested). The durable target for a focused next attempt: make the adopted-import / namespace builder for a CJS module reflect its runtime module.exports.