Skip to content

Commit 62e7883

Browse files
fix(solid): route pre-flush Loading rejections through the fragment channel (#2997)
An async rejection landing before the shell flushed under Errored > Loading rendered a permanently blank region: the server called the enclosing Errored's handler at async time, whose rendered fallback had no consumer, while the error record it serialized at the boundary id derailed the hydrating client into claiming fallback DOM that was never emitted. Once a boundary's fragment is registered, its channel now owns error routing — `<key>_fr` rejects and the client re-renders the subtree fresh, letting the client-side Errored catch, exactly like the post-flush path. The sync discovery pass (pull still on the stack) keeps parent-handler routing and inline fallbacks. Client-side, the serialized rejected flight and subFetch trace runs now observe rejections so adoption doesn't leak unhandled rejection noise. Co-authored-by: Cursor <[email protected]>
1 parent 8366208 commit 62e7883

7 files changed

Lines changed: 164 additions & 17 deletions

File tree

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
"solid-js": patch
3+
---
4+
5+
Fix blank page when an async read rejects before the SSR shell flushes under
6+
`Errored > Loading` (#2997). The fragment channel now owns the error once the
7+
boundary has registered: `<key>_fr` rejects and the client re-renders the
8+
subtree as fresh DOM (adopting the serialized rejection), letting the
9+
client-side Errored catch it — matching post-flush semantics. Previously the
10+
server also invoked the enclosing Errored's handler at async time; its
11+
rendered fallback had no consumer, and the error record it serialized at the
12+
boundary id made the hydrating client try to claim fallback DOM that was
13+
never emitted, derailing hydration into a permanently blank region. Also
14+
defuses the two client-side unhandled-rejection leaks in this flow (the
15+
serialized rejected flight consumed via its stamp, and the trace-run promise
16+
in `subFetch`).
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"name": "errored-loading-preflush-rejection",
3+
"shell": "<div _hk=1><!--$--><!--/--><span>tail</span></div><script>(self.$R=self.$R||{})[\"\"]=[];_$HY.r[\"0\"]=$R[0]=($R[1]=($R[2]=() => {\n const resolver = {\n p: 0,\n s: 0,\n f: 0\n };\n resolver.p = new Promise((resolve, reject) => {\n resolver.s = resolve;\n resolver.f = reject;\n });\n return resolver;\n})()).p;_$HY.r[\"200_fr\"]=$R[3]=($R[4]=$R[2]()).p;($R[6]=(resolver, data) => {\n resolver.f(data);\n resolver.p.s = 2;\n resolver.p.v = data;\n})($R[1],$R[5]=new Error(\"boom\"));$R[6]($R[4],$R[5]);</script>",
4+
"rest": ""
5+
}

‎packages/solid-web/test/harness/scenarios.tsx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1290,6 +1290,31 @@ function BareClientLateFinal() {
12901290
);
12911291
}
12921292

1293+
// ---------------------------------------------------------------------------
1294+
// #2997: an async rejection that lands BEFORE the shell flushes, with the
1295+
// boundary order Errored > Loading > read. The fragment channel owns the
1296+
// error: the server inlines the placeholder away and rejects `<key>_fr`; the
1297+
// client re-renders the boundary's subtree as fresh DOM (the memo adopts the
1298+
// serialized rejection) and the client-side Errored catches it. The server
1299+
// must NOT serialize the error at the Errored id — its async-time fallback
1300+
// render has no consumer, and the record would make the hydrating client
1301+
// expect fallback DOM that was never emitted (the blank-forever regression).
1302+
function PreflushRejection() {
1303+
const data = createMemo(async (): Promise<string> => {
1304+
throw new Error("boom");
1305+
});
1306+
return (
1307+
<div>
1308+
<Errored fallback={<p>caught</p>}>
1309+
<Loading fallback={<i>loading</i>}>
1310+
<span>value:{data()}</span>
1311+
</Loading>
1312+
</Errored>
1313+
<span>tail</span>
1314+
</div>
1315+
);
1316+
}
1317+
12931318
export const scenarios: Scenario[] = [
12941319
{
12951320
name: "text-hole",
@@ -1732,5 +1757,14 @@ export const scenarios: Scenario[] = [
17321757
// text node into the range (see expectedTextStreamed).
17331758
expectedTextStreamed: " widgettail",
17341759
serverText: "wait"
1760+
},
1761+
{
1762+
name: "errored-loading-preflush-rejection",
1763+
App: PreflushRejection,
1764+
async: true,
1765+
expectedText: "caughttail",
1766+
// Pre-flush the rejected boundary inlines to an empty region: neither
1767+
// fallback reaches the server HTML — only the static sibling.
1768+
serverText: "tail"
17351769
}
17361770
];

‎packages/solid-web/test/server/ssr-stream.spec.tsx‎

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -288,10 +288,13 @@ describe("SSR Streaming — Basic Rendering", () => {
288288

289289
// Without the rejection capture in lazy(), the failed module load left the
290290
// render memo throwing NotReadyError forever (the stream never completes)
291-
// and leaked a process-level unhandledRejection. The render now completes,
292-
// and — because the boundary's region was already streamed (Loading
293-
// placeholder) — the error reaches `<Errored>` and is serialized at its id
294-
// for the client to render the fallback via the streamed-fragment path.
291+
// and leaked a process-level unhandledRejection. The render now completes:
292+
// the fragment channel carries the error (`_fr` rejects with the payload)
293+
// and the client re-renders the subtree fresh — re-importing the module
294+
// and routing a repeat failure to its own Errored. The boundary id must
295+
// NOT carry an error record (#2997): the server rendered no fallback DOM,
296+
// so a record would derail the hydrating Errored into claiming markup
297+
// that does not exist.
295298
const html = await renderComplete(
296299
() => (
297300
<Errored fallback={(e: any) => <span>err: {String(e()?.message || e())}</span>}>
@@ -303,13 +306,48 @@ describe("SSR Streaming — Basic Rendering", () => {
303306
{ manifest }
304307
);
305308
const rKeys = [...html.matchAll(/_\$HY\.r\["([^"]+)"\]/g)].map(m => m[1]);
306-
// Error captured and serialized at the boundary id, the streamed fragment
307-
// settled (rejected), and the shell did not get stuck on the placeholder.
309+
// Error captured (it rides the rejected fragment), the streamed fragment
310+
// settled, and the shell did not get stuck on the placeholder.
308311
expect(html).toContain("lazy failed");
309-
expect(rKeys).toContain("0");
312+
expect(rKeys).not.toContain("0");
310313
expect(rKeys).toContain("000_fr");
311314
});
312315

316+
test("pre-flush rejection under Errored > Loading rejects the fragment without a boundary error record (#2997)", async () => {
317+
// Rejects before its first await — the rejection lands before the shell
318+
// can flush.
319+
function Child() {
320+
const data = createMemo(async (): Promise<string> => {
321+
throw new Error("boom");
322+
});
323+
return <span>value:{data()}</span>;
324+
}
325+
326+
const html = await renderComplete(() => (
327+
<div>
328+
<Errored fallback={<p>caught</p>}>
329+
<Loading fallback={<i>loading</i>}>
330+
<Child />
331+
</Loading>
332+
</Errored>
333+
<span>tail</span>
334+
</div>
335+
));
336+
337+
const rKeys = [...html.matchAll(/_\$HY\.r\["([^"]+)"\]/g)].map(m => m[1]);
338+
// The fragment channel owns the error: `_fr` rejects (the client
339+
// re-renders the subtree fresh and its Errored catches), and the memo's
340+
// rejected flight is serialized for adoption. The Errored boundary id
341+
// must NOT carry an error record — the server never rendered fallback
342+
// DOM for it, so a record would make the hydrating client claim against
343+
// markup that does not exist and derail hydration into a blank page.
344+
expect(html).toContain("tail");
345+
expect(html).toContain("boom");
346+
expect(rKeys.sort()).toEqual(["100000", "100_fr"]);
347+
// The static sibling survives; neither fallback is server-rendered.
348+
expect(html).not.toContain("caught");
349+
});
350+
313351
test("async memo — shell contains fallback, final has resolved value", async () => {
314352
function App() {
315353
const data = createMemo(async () => {

‎packages/solid/src/client/hydration.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -327,6 +327,12 @@ function subFetch<T>(fn: (prev?: T) => any, prev?: T) {
327327
if (result && typeof result[Symbol.asyncIterator] === "function") {
328328
result[Symbol.asyncIterator]().next();
329329
}
330+
// The trace run's flight is never consumed (the serialized value is
331+
// authoritative) — an async fn returns a REAL promise (engine-internal,
332+
// the MockPromise swap can't intercept it), so a rejecting compute
333+
// (#2997: server-rejected async adopted on the client) must be observed
334+
// here or it surfaces as an unhandled rejection.
335+
if (result && typeof result.then === "function") result.then(undefined, () => {});
330336
return result;
331337
} finally {
332338
window.fetch = ogFetch;
@@ -363,7 +369,13 @@ function readHydratedValue(initP: any, refresh: () => void, options?: any) {
363369
// fast-adopt): the landing applies on the microtask after the walk.
364370
if (hasLoadingWindow(options) && typeof initP.then === "function")
365371
return { then: initP.then.bind(initP) };
366-
if (initP.s === 2) throw initP.v;
372+
if (initP.s === 2) {
373+
// The stamp is the consumption: nothing ever `.then`s the serialized
374+
// promise itself, so observe its rejection here or the deserialized
375+
// record surfaces as an unhandled rejection (#2997).
376+
if (typeof initP.then === "function") initP.then(undefined, () => {});
377+
throw initP.v;
378+
}
367379
if (initP.s === 1) return initP.v;
368380
}
369381
return initP;

‎packages/solid/src/server/hydration.ts‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,23 @@ function ssrLoadingBoundary(
124124
render,
125125
(err: any, parentHandler) => {
126126
handledRenderError = err;
127-
if (done?.(undefined, err)) throw err;
127+
if (done) {
128+
// Once the fragment is registered, its channel owns error routing:
129+
// `<key>_fr` rejects and the client re-renders the subtree as fresh
130+
// DOM, letting a client-side Errored catch (post-flush this rides
131+
// the sink; pre-flush the placeholder inlines away, #2997). The
132+
// parent handler must NOT hear about it here — an async-time
133+
// Errored render has no consumer (the accessor pull is long gone),
134+
// so its only lasting effect is serializing the error at the
135+
// Errored id, which makes the hydrating client render the error
136+
// fallback expecting server DOM that was never emitted, derailing
137+
// hydration before the fragment channel can engage.
138+
done(undefined, err);
139+
throw err;
140+
}
141+
// Synchronous discovery (no fragment yet): the enclosing Errored's
142+
// pull is still on the stack, so its handler renders the fallback
143+
// inline and serializes the error for matching client adoption.
128144
if (parentHandler) {
129145
parentHandler(err);
130146
return;

‎packages/solid/test/server/ssr-async.spec.ts‎

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,8 @@ function createMockSSRContext(options: { async?: boolean; fragmentFlushed?: bool
156156
const registeredFragments = new Set<string>();
157157
const fragmentResults = new Map<string, string | undefined>();
158158
const fragmentErrors = new Map<string, any>();
159+
/** Every done() invocation, including pre-flush ones the maps above skip. */
160+
const fragmentSettles: Array<{ key: string; value?: string; error?: any }> = [];
159161
const fragmentFlushed = options.fragmentFlushed ?? true;
160162

161163
const context: any = {
@@ -174,6 +176,7 @@ function createMockSSRContext(options: { async?: boolean; fragmentFlushed?: bool
174176
registerFragment(key: string) {
175177
registeredFragments.add(key);
176178
return (value?: string, error?: any) => {
179+
fragmentSettles.push({ key, value, error });
177180
if (fragmentFlushed) {
178181
fragmentResults.set(key, value);
179182
if (error !== undefined) fragmentErrors.set(key, error);
@@ -183,7 +186,14 @@ function createMockSSRContext(options: { async?: boolean; fragmentFlushed?: bool
183186
}
184187
};
185188

186-
return { context, serialized, registeredFragments, fragmentResults, fragmentErrors };
189+
return {
190+
context,
191+
serialized,
192+
registeredFragments,
193+
fragmentResults,
194+
fragmentErrors,
195+
fragmentSettles
196+
};
187197
}
188198

189199
/** Wait for microtasks and pending async to settle. */
@@ -1034,10 +1044,11 @@ describe("Loading SSR Async", () => {
10341044
).toBe(true);
10351045
});
10361046

1037-
test("outer Errored claims late Loading rejection before flush", async () => {
1038-
const { context, fragmentResults, fragmentErrors, serialized } = createMockSSRContext({
1039-
fragmentFlushed: false
1040-
});
1047+
test("pre-flush Loading rejection rides the fragment channel, not the outer Errored (#2997)", async () => {
1048+
const { context, fragmentResults, fragmentErrors, fragmentSettles, serialized } =
1049+
createMockSSRContext({
1050+
fragmentFlushed: false
1051+
});
10411052
sharedConfig.context = context;
10421053

10431054
const d = deferred<string>();
@@ -1075,13 +1086,28 @@ describe("Loading SSR Async", () => {
10751086
d.reject(fetchError);
10761087
await tick();
10771088

1078-
expect(fallbackCalls).toBe(1);
1079-
expect(read(result)).toBe("OuterError: Async fetch failed");
1089+
// The fragment channel owns the error once the boundary registered:
1090+
// done(undefined, err) settles the fragment (pre-flush the renderer
1091+
// inlines the placeholder away and rejects `<key>_fr`; the client
1092+
// re-renders the subtree fresh and its Errored catches). The outer
1093+
// Errored's handler must NOT run at async time — its rendered fallback
1094+
// would have no consumer (the accessor pull is long gone), and the
1095+
// serialized error record it leaves at the boundary id sends the
1096+
// hydrating client claiming fallback DOM that was never emitted — the
1097+
// #2997 blank page.
1098+
expect(fallbackCalls).toBe(0);
1099+
expect(fragmentSettles).toEqual([{ key: "t000", value: undefined, error: fetchError }]);
10801100
expect(fragmentResults.size).toBe(0);
10811101
expect(fragmentErrors.size).toBe(0);
10821102
expect(
10831103
[...serialized.values()].some(v => v instanceof Error && v.message === "Async fetch failed")
1084-
).toBe(true);
1104+
).toBe(false);
1105+
1106+
// A later re-creation of the Errored (re-pull) still claims the settled
1107+
// rejection synchronously — the pull is on the stack, so the fallback
1108+
// render has a consumer.
1109+
expect(read(result)).toBe("OuterError: Async fetch failed");
1110+
expect(fallbackCalls).toBe(1);
10851111
});
10861112

10871113
test("outer Errored stays out of post-flush Loading rejection ownership", async () => {

0 commit comments

Comments
 (0)