[Fizz] Allow Pending Work to Specialize Abort Reasons#36586
Merged
Conversation
github-actions
Bot
added
the
React Core Team
|
Comparing: 557e28f...41f759b Critical size changesIncludes critical production bundles, as well as any change greater than 2%:
Significant size changesIncludes any change greater than 0.2%: Expand to show |
unstubbable
reviewed
Jun 1, 2026
Collaborator
There was a problem hiding this comment.
It's nice how simple and clean the final commit is because of the preparatory work that went into the preceding PRs.
One (possibly naïve) question about the causality:
Using the same AbortSignal to notify data sources is the intended protocol, but Fizz cannot distinguish a rejection caused by that signal from any unrelated rejection that happens to occur during the abort window.
What if we made the contract so that a rejected wakeable would need to use the abort signal's reason as its cause? That would allow us to ignore unrelated rejections that just coincidentally happened to occur between starting and finishing the abort, wouldn't it?
E.g. (building on your "Intended Usage" example):
signal.addEventListener('abort', () => {
reject(new TimeoutError('optional recommendations timed out', {cause: signal.reason}));
});And then in pingRejectedTask we could compare error.cause with request.fatalError, I suppose.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
Collaborator
Author
I had considered that. It's attractive because it provides more certainty about the provenance. It does limit what you can specialize with to errors and error-like objects. I.e. you can't specialize to a string. But that's probably not of much practical concern. Interestingly it seems fetch will reject the fetch with the AbortSignal's reason without a wrapper Error so if this pattern is common in the wild it may be a noop functionally since the lack of cause will still be interpretted as rejecting for the reason. The reason I didn't implement it that way at first was just because it felt finicky if you end up forgetting to "link" the specialized reason to the original you lose out on that extra context. And if an unassociated error ends up sneaking in it doesn't seem harmful to misinterpret it as caused by the abort. If it arrived slightly sooner you'd see that error in the onError list. If it arrived slightly later you'd miss it entirely. The biggest risk is if it arrives in the gap and you use the status of "already aborted" to do something with that info that would be incorrect if it weren't really from the abort, but tbh I can't even think of a plausible scenario where that would be the case. And then on top of that if you really cared about this extra restriction you could enforce yourself in onError that the reason must have the abort reason as a cause otherwise you'll consider it a normal error. |
Fizz currently reports every unfinished task using the request-wide abort reason. This is generally sufficient for ordinary renders, where aborting primarily means stopping output, but it is limiting for partial prerendering because abort is the API used to intentionally leave parts of the tree unfinished. Callers may want to treat a known slow optional API as an expected prerender miss while still surfacing other unfinished work as actionable feedback, or allow a data source to provide operation-specific telemetry once it learns that prerendering was aborted. This change lets a suspended task report the rejection from the wakeable it was blocked on when that rejection arrives after abort begins and before Fizz finalizes that task. Tasks that remain pending continue to report the request-wide abort reason, and rejections that arrive after finalization are ignored. The intended pattern is to use the same AbortSignal both to abort the prerender and to notify pending data sources, allowing those sources to reject with slot-specific reasons. Fizz does not attempt to prove that a rejection was caused by the abort signal. Any suspended wakeable that rejects during the abort window can specialize the reason for its task. Callers can use signal.aborted in onError to distinguish ordinary render errors observed before abort from unfinished-work errors observed after abort begins, but this does not establish causality for arbitrary asynchronous rejections. To support this without adding another top-level field to Task, ping now contains separate resolve and reject callbacks. Before abort begins, rejected wakeables retain the existing retry behavior so ordinary render errors continue through the normal error path. After abort begins, a rejected ping claims its still-pending task from its abort set and finalizes it using the rejection reason; the scheduled abort finish applies the general abort reason only to remaining tasks. This also covers suspension sources such as React.lazy, which cannot be handled by inspecting use() thenable state alone. Tests cover specialization alongside unrelated pending work that retains the general abort reason, React.lazy specialization, dropping rejections that arrive after abort completion, and the prerender scheduling window that lets abort listeners reject pending work before abort finishes.
gnoff
force-pushed
the
jstory/specialize-abort-reason
branch
from
4a2589c to
41f759b
Compare
unstubbable
approved these changes
Jun 1, 2026
github-actions Bot
pushed a commit
that referenced
this pull request
Jun 3, 2026
# Allow Pending Work to Specialize Abort Reasons
## Summary
Fizz currently reports every unfinished task using the same request-wide
abort reason. This makes it possible to observe that a render did not
finish, but not to understand why any individual suspended slot remained
incomplete.
This change allows suspended tasks to report a more specific rejection
reason when the wakeable they are blocked on rejects after abort begins
and before Fizz finalizes that task. Tasks that do not reject during
this window continue to report the general abort reason.
This is primarily motivated by partial prerendering, where aborting is
not merely an exceptional termination mechanism. It is the API used to
intentionally finish a prerender while leaving some work unresolved.
## Motivation
For an ordinary server render, a request abort generally means that the
result is no longer needed. Reporting the same abort reason for every
unfinished task is usually sufficient.
For a partial prerender, the meaning is different. The caller
intentionally aborts in order to produce a partial result. The
unfinished work is then useful information: it identifies which parts of
the tree prevented the prerender from completing.
Today, all of those tasks receive the same abort reason:
```text
slot A -> prerender aborted
slot B -> prerender aborted
slot C -> prerender aborted
```
That says which work was incomplete, but not whether different slots
should be interpreted differently.
For example, an application may have:
- A slow API that is permitted to miss the prerender deadline and should
not produce actionable logging.
- Other work that is expected to finish during prerendering and should
be reported when it does not.
- A data source that can provide additional telemetry about why it did
not finish once it learns that the prerender has been aborted.
With a single request-wide abort reason, `onError` cannot distinguish
these cases.
## Proposed Behavior
When abort begins, Fizz still associates a general abort reason with the
request. That reason remains the fallback for every unfinished task.
However, if a task is suspended on a wakeable and that wakeable rejects
during the interval between:
1. The request beginning to abort.
2. Fizz finalizing that task as aborted.
then Fizz reports the wakeable's rejection reason for that task instead
of the general abort reason.
Conceptually:
```text
slot A -> rejected during abort with TimeoutError("optional recommendations timed out")
slot B -> still pending when abort finishes -> Error("prerender deadline reached")
slot C -> rejected during abort with QueryError("inventory lookup canceled")
```
A rejection that arrives after its task has already been finalized is
ignored.
## Intended Usage
The canonical usage is for the caller to use the same `AbortSignal` both
to terminate the prerender and to notify data sources that may still be
blocking suspended work. A data source can reject with a more specific
error whose `cause` preserves its relationship to the overall abort.
```js
const controller = new AbortController();
const abortReason = new Error('prerender deadline reached');
const result = prerender(<App signal={controller.signal} />, {
signal: controller.signal,
onError(error) {
if (error === abortReason) {
// This task was unfinished but did not provide a more specific reason.
return;
}
if (error instanceof Error && error.cause === abortReason) {
// This task reported a specialized failure caused by the prerender abort.
// For example, suppress an expected optional timeout or record telemetry.
return;
}
// Interpret an ordinary rendering error.
},
});
controller.abort(abortReason);
```
An interested data source can observe that signal and reject pending
work with an operation-specific reason that records the abort as its
cause:
```js
signal.addEventListener(
'abort',
() => {
reject(
new Error('optional recommendations timed out', {
cause: signal.reason,
}),
);
},
{once: true},
);
```
If this rejection arrives before Fizz finishes aborting the suspended
task, `onError` receives the operation-specific error instead of the
general abort reason. Work that does not provide a specialized rejection
continues to report `abortReason` directly.
This allows applications to:
- Suppress logging for intentionally optional or deadline-limited work.
- Surface unfinished work that should be investigated.
- Include operation-specific telemetry or context in aborted-slot
reporting.
- Retain an explicit causal relationship between a specialized error and
the request-wide abort.
## Causality And Scope
Fizz does not attempt to prove that a wakeable rejected because of the
abort signal.
The precise behavior is temporal:
- If a suspended wakeable rejects after abort begins and before its task
is finalized, its rejection specializes that task's abort reason.
- If it does not reject during that interval, the task receives the
general abort reason.
- If it rejects after finalization, the rejection is ignored for Fizz
error reporting.
Using the same `AbortSignal` to notify data sources is the intended
protocol, but Fizz cannot distinguish a rejection caused by that signal
from any unrelated rejection that happens to occur during the abort
window.
Likewise, `signal.aborted` in `onError` lets callers distinguish errors
observed before abort initiation from errors observed after it began. It
does not independently prove causality for an arbitrary rejection.
## Implementation
Previously, a suspended task attached the same ping callback for both
fulfillment and rejection:
```js
wakeable.then(ping, ping);
```
That is correct during ordinary rendering because retrying the task
allows a rejected wakeable to throw through the normal render path,
preserving regular error handling and stack construction.
During abort, however, retrying general work is intentionally
suppressed. To preserve a rejection that arrives during the abort
window, the task now stores distinct fulfillment and rejection ping
callbacks:
```js
wakeable.then(ping.resolve, ping.reject);
```
Before abort begins, `ping.reject` retains existing behavior by
scheduling the task for retry.
After abort begins, `ping.reject` attempts to claim the still-pending
aborted task from its owning abort set. If successful, Fizz finalizes
that task immediately using the rejection reason. The later scheduled
abort finish processes only tasks that remain in their abort sets, using
the general abort reason.
This avoids adding another top-level property to `Task`, whose
production shape is already at the current field-count threshold, while
also covering suspension mechanisms such as `React.lazy` that cannot be
handled by inspecting `use()` thenable state.
## Tests
The tests cover:
- A rejected suspended task reporting a specialized reason while
unrelated pending work still reports the general abort reason.
- Specialization for `React.lazy`, ensuring this is not limited to
`use()` suspension.
- A rejection arriving after abort finalization being ignored.
- The prerender scheduling window in both static Browser and Node APIs,
where abort listeners can reject pending work before abort completion.
DiffTrain build for [43bcbf8](43bcbf8)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Allow Pending Work to Specialize Abort Reasons
Summary
Fizz currently reports every unfinished task using the same request-wide abort reason. This makes it possible to observe that a render did not finish, but not to understand why any individual suspended slot remained incomplete.
This change allows suspended tasks to report a more specific rejection reason when the wakeable they are blocked on rejects after abort begins and before Fizz finalizes that task. Tasks that do not reject during this window continue to report the general abort reason.
This is primarily motivated by partial prerendering, where aborting is not merely an exceptional termination mechanism. It is the API used to intentionally finish a prerender while leaving some work unresolved.
Motivation
For an ordinary server render, a request abort generally means that the result is no longer needed. Reporting the same abort reason for every unfinished task is usually sufficient.
For a partial prerender, the meaning is different. The caller intentionally aborts in order to produce a partial result. The unfinished work is then useful information: it identifies which parts of the tree prevented the prerender from completing.
Today, all of those tasks receive the same abort reason:
That says which work was incomplete, but not whether different slots should be interpreted differently.
For example, an application may have:
With a single request-wide abort reason,
onErrorcannot distinguish these cases.Proposed Behavior
When abort begins, Fizz still associates a general abort reason with the request. That reason remains the fallback for every unfinished task.
However, if a task is suspended on a wakeable and that wakeable rejects during the interval between:
then Fizz reports the wakeable's rejection reason for that task instead of the general abort reason.
Conceptually:
A rejection that arrives after its task has already been finalized is ignored.
Intended Usage
The canonical usage is for the caller to use the same
AbortSignalboth to terminate the prerender and to notify data sources that may still be blocking suspended work. A data source can reject with a more specific error whosecausepreserves its relationship to the overall abort.An interested data source can observe that signal and reject pending work with an operation-specific reason that records the abort as its cause:
If this rejection arrives before Fizz finishes aborting the suspended task,
onErrorreceives the operation-specific error instead of the general abort reason. Work that does not provide a specialized rejection continues to reportabortReasondirectly.This allows applications to:
Causality And Scope
Fizz does not attempt to prove that a wakeable rejected because of the abort signal.
The precise behavior is temporal:
Using the same
AbortSignalto notify data sources is the intended protocol, but Fizz cannot distinguish a rejection caused by that signal from any unrelated rejection that happens to occur during the abort window.Likewise,
signal.abortedinonErrorlets callers distinguish errors observed before abort initiation from errors observed after it began. It does not independently prove causality for an arbitrary rejection.Implementation
Previously, a suspended task attached the same ping callback for both fulfillment and rejection:
That is correct during ordinary rendering because retrying the task allows a rejected wakeable to throw through the normal render path, preserving regular error handling and stack construction.
During abort, however, retrying general work is intentionally suppressed. To preserve a rejection that arrives during the abort window, the task now stores distinct fulfillment and rejection ping callbacks:
Before abort begins,
ping.rejectretains existing behavior by scheduling the task for retry.After abort begins,
ping.rejectattempts to claim the still-pending aborted task from its owning abort set. If successful, Fizz finalizes that task immediately using the rejection reason. The later scheduled abort finish processes only tasks that remain in their abort sets, using the general abort reason.This avoids adding another top-level property to
Task, whose production shape is already at the current field-count threshold, while also covering suspension mechanisms such asReact.lazythat cannot be handled by inspectinguse()thenable state.Tests
The tests cover:
React.lazy, ensuring this is not limited touse()suspension.