[2.0] lazy() hydration outside <Loading> silently halts reactivity

[ethan-huo]

Describe the bug

In Solid 2 SSR/hydration, a code-split route rendered through lazy() without an enclosing <Loading> boundary can leave the whole reactive system halted after hydration.

The server-rendered DOM remains visible, so the page looks hydrated, but signals and event-driven updates after the lazy route no longer run. The only observable diagnostic in our app was console.error; neither window.onerror nor unhandledrejection received an event, and there was no error value that the application could handle programmatically.

This is not a request to make lazy() work without a Loading boundary. The current lazy() contract documents that it suspends through an enclosing <Loading>, and the hydration error itself says to ensure that it is inside one. The problem is the failure mode when that invariant is missed: a contained, actionable hydration error would be much safer than a page that silently stops responding.

The issue was encountered through @solidjs/router's fileRoutes() adapter, which turns code-split route entries into Solid lazy() components. The router is only the trigger; the failure is in the Solid hydration/reactivity boundary.

Your Example Website or App

No public reproduction is available yet. The minimal shape is included below; the original reproduction was in a private Solid 2 SSR app.

import { lazy } from "solid-js";
import { createRouter } from "@solidjs/router";

const Page = lazy(() => import("./Page"), undefined, "/src/Page.tsx");
const Router = createRouter({ routes: [{ path: "/", component: Page }] });

// In an SSR app, mount the router outlet directly, without <Loading>:
<Router>{props => <>{props.children}</>}</Router>;

Steps to Reproduce the Bug or Issue

1. Run a Solid 2 SSR application with a code-split route (lazy() or fileRoutes() with code splitting enabled).
2. Render the router's matched children directly, without an enclosing <Loading> boundary.
3. Load the route with SSR and let the browser hydrate it.
4. Observe that the SSR markup remains visible and the console reports the missing lazy hydration preload / Ensure it is inside a Loading boundary diagnostic.
5. Trigger an unrelated signal update or event handler after hydration.

The route content stays on screen, but the reactive graph no longer processes subsequent updates. In our application there was no window.onerror or unhandledrejection event for the failure.

Expected behavior

If a lazy component is rendered outside the required <Loading> boundary, hydration should fail in a contained and observable way: for example, by reaching an ErrorBoundary, dispatching a browser-level error, or exposing a documented programmatic failure signal. The application should not appear hydrated while the global reactive system is silently halted.

Platform

• OS: macOS
• Browser: Chrome
• solid-js: 2.0.0-rc.6
• @solidjs/web: 2.0.0-rc.6
• @solidjs/router: 2.0.0-next.21
• @solidjs/vite-plugin: 3.0.0-next.39

Additional context

The application workaround is either to wrap the router outlet in <Loading fallback={null}> or to disable route code splitting. The root boundary has a separate streaming SSR trade-off: a catch-all 404 may commit as HTTP 200 after the shell flushes.

Related Solid 2 hydration/lazy fixes include #2860 and #3012, but this report is about the missing error signal and global reactive halt when the required boundary is absent.

[ryansolid]

Thanks for the detailed report. One correction up front, because it changes the diagnosis: lazy() does not require a <Loading> boundary, at the root or anywhere else. Root-level lazy hydration is a supported path with dedicated plumbing — the server serializes a root module map (_$HY.r["_assets"]) and hydrate() preloads it before rendering. The error message that told you otherwise was wrong, and I'm sorry it sent you down that path.

What we could reproduce. I built your stack (solid-v2/fullstack template: solid rc.6, router next.21, vite-plugin next.38) with the <Loading> removed and the router outlet rendered bare. Index route, a lazy layout with a nested lazy child, and the 404 catch-all all hydrate and stay reactive, in dev and in a production build. So the plain shape works.

Your exact symptom appears when the server cannot resolve client assets for the lazy module's key. Forcing that (a moduleUrl absent from the build manifest) gives, to the letter: the server logs Asset manifest returned no client assets for module "…" and ships no root map; the client throws lazy() module "…" was not preloaded before hydration, from inside the router's outlet memo, so the reactive system converts it to status and halts — one console.error, no window.onerror, no unhandledrejection, _$HY.done === true, server DOM on screen, every update dead. Note the same thing happens with a missing manifest key with <Loading> in my repro (sync and streamed), so I don't yet understand why the boundary fixed it for you.

What changed (fe3ab92 on next):

• The client error now names the actual cause — the server serialized no client entry for this id; check the server log for Asset manifest returned no client assets for module — instead of pointing at a boundary.
• An uncaught error that halts the reactive system is now handed to reportError, so it reaches window.onerror / error monitoring. Creation-time throws (this case) never reached the top before; console.error was the only trace.
• hydrate()'s "preload failed → fall back to client render" path no longer runs for a document root (a document shell can't be client-rendered; it died with an unrelated Hydration Mismatch unhandled rejection). It now reports an explicit error carrying the preload failure as its cause.

What we need from you to find the actual trigger in your app:

1. Your server log for the request. If the theory is right it contains Asset manifest returned no client assets for module "<key>" — that key is the thing that didn't resolve.
2. The exact moduleUrl string reaching lazy(). Your sketch has a leading slash ("/src/Page.tsx"); the plugin's key format is project-relative (src/Page.tsx), and a leading slash produced an unfetchable //src/Page.tsx entry URL in my test. If that's literal rather than a paraphrase, it may be the whole story.
3. Ideally a minimal public reproduction — a solid-v2/fullstack template with the <Loading> removed is a fine starting point.

— Claude via Cursor

[brenelz]

I tried to reproduce this on your exact stack: the solid-v2/fullstack template pinned to solid-js / @solidjs/web 2.0.0-rc.6, @solidjs/router 2.0.0-next.21, @solidjs/vite-plugin 3.0.0-next.39 (with @solidjs/signals pinned to rc.6 — a fresh install today resolves rc.7, whose dropped exports make dep optimization fail outright), <Loading> removed, router outlet rendered bare through fileRoutes(). Dev server and a production build served by the template's server.js, with error / unhandledrejection / console.error hooked per page load.

The plain shape works. / (lazy index), /users/1 (lazy layout + nested lazy child) and the catch-all all hydrate and stay reactive in dev and prod. Same conclusion as the comment above.

Your sketch as written reproduces your symptom exactly. The leading slash in lazy(() => import("./Page"), undefined, "/src/Page.tsx") is enough:

• Production: the server logs Asset manifest returned no client assets for module "/src/Page.tsx", ships no root module map, and the client throws lazy() module "/src/Page.tsx" (hydration id "…") was not preloaded before hydration. Ensure it is inside a Loading boundary. from the router outlet. REACTIVITY_HALTED, one console.error, nothing on window.onerror or unhandledrejection, server markup on screen, every signal dead.
• Dev: the map is serialized as //src/Page.tsx (protocol-relative), the preload fetches http://src/Page.tsx, fails, and hydrate() falls back to a client render that dies with an unhandled Hydration Mismatch … key: undefined.

The plugin's key format is project-relative (src/Page.tsx), so if that slash is in your real code rather than a paraphrase, that is the whole story.

A second, deterministic dead page you may actually be hitting: the catch-all in production. [...404].tsx builds to a client chunk named _...404_-<hash>.js. The template's server.js refuses any URL containing .. as path-traversal protection, so the chunk request falls through to SSR and comes back as the 404 HTML:

$ curl -i http://localhost:3000/assets/_...404_-BW0HgTxD.js
HTTP/1.1 404 Not Found
content-type: text/html; charset=utf-8

The module preload then fails. Without a boundary the document-root fallback dies with Hydration Mismatch and the page is dead. With <Loading fallback={null}> the boundary re-imports the chunk on the client, fails again, and the whole root is replaced by the entry's Error | Uncaught Client Exception banner. Any [...rest] route is affected, and any static host, CDN or WAF with a traversal guard would do the same thing to that filename.

Two questions that would pin it down: was the route that broke a catch-all (or anything whose chunk name contains ..)? And does your server log show Asset manifest returned no client assets for module for the request?

Where the fixes live. A fix to the template's server.js (resolved-path containment instead of a substring check) is in progress. The plugin should stop emitting .. inside chunk file names and normalize a leading slash on moduleUrl in both the dev bridge and the build manifest lookup. On the core side, fe3ab92 / 711b557 already make the failure name its real cause and reach reportError.

One more thing I saw only in dev: on the very first load, vite's mid-page dependency re-optimization ("optimized dependencies changed. reloading") briefly ran two Solid instances, misaligned the hydration ids, and produced this same halt until the automatic reload. Transient, but it looks identical in the console for a few seconds.

— Claude, via Claude Code (posted on Brenley's behalf)