@defer'd fragment returns partial data instead of suspending when the parent record is populated by a sibling non-deferred query

[jonreading81]

Version

react-relay / relay-runtime 21.0.1, with React 19 streaming SSR + @defer.

Problem

Under React 19 streaming SSR of a query with @defer, useFragment reads partial data instead of suspending, while the underlying OperationExecutor is still emitting incremental payloads. Consumers that expect the fragment's fields to be either fully present (fragment resolved) or absent (fragment suspended) crash on undefined subtree fields.

Fix proposed in #5360.

Root cause

fetchQueryDeduped caches a per-identifier subject and tears it down when subscriber count hits 0. Under React 19 streaming SSR, that cleanup fires between Suspense render passes for a query still emitting @defer chunks — the subject is torn down while the executor is alive. From that moment on:

1. getPromiseForActiveRequest returns null (the cache entry has been deleted).
2. RelayOperationTracker.getPendingOperationsAffectingOwner returns null (no other operation writes to the owner's records — this is the specifically-broken case when a sibling non-deferred query has already populated the shared record).
3. getPendingOperationsForFragment returns null.
4. useFragment reads the partial snapshot and returns non-suspended data.

The condition surfaces most obviously when a sibling non-deferred query has already populated the shared record — viewer.me exists, but viewer.me.commentsReceived (owned by the deferred fragment) does not — because that's the state where partial-data reads look "consistent enough" to render but crash on a specific field. Structurally, the underlying gap (request-cache drained between Suspense passes) affects any streaming operation whose executor outlives its cache subject.

Minimal shape

Two queries preloaded on the same page.

Query A (non-deferred, populates viewer.me in the store):

query SiblingQuery {
    viewer {
        me {
            username
            hasProFeatures
        }
    }
}

Query B (defers a fragment that reads other fields on the same viewer.me):

query MyDashboardQuery($itemCount: Int!) {
    viewer {
        ...LatestCommentsList_viewer @defer @arguments(itemCount: $itemCount)
    }
}

fragment LatestCommentsList_viewer on Viewer @argumentDefinitions(itemCount: {type: "Int!"}) {
    me {
        commentsReceived(first: $itemCount) {
            edges { ...CommentCardList_commentEdges }
        }
    }
}

SiblingQuery completes first, populating viewer.me. During SSR of the consumer of LatestCommentsList_viewer:

• viewer → present
• viewer.me → present (from SiblingQuery)
• viewer.me.commentsReceived → undefined (still in the deferred chunk of MyDashboardQuery)

useFragment returns { me: { …siblingFields }, commentsReceived: undefined } instead of suspending.

Repro fingerprint

Switched to client rendering because the server rendering errored:
TypeError: Cannot read properties of undefined (reading 'edges')
    at LatestCommentsList (…/index.jsx:59:34)

Expected behaviour

useFragment for a fragment whose data has not yet arrived (spread was @defer'd, no deferred chunk applied) should suspend regardless of whether the parent record identity exists in the store from another query. Otherwise every consumer must defensively null-guard every field their fragment selects, defeating the point of generated non-null types.

Fix

#5360 — introduces a per-environment registry of operation completion promises tied to OperationExecutor lifetime, independent of the request-cache subject and its subscriber count. getPendingOperationsForFragment consults it as a last-resort correlation. Gated behind RelayFeatureFlags.ENABLE_IN_FLIGHT_OPERATION_CORRELATION (default off).

Related

#5354 — distinct-but-related: @defer on a fragment-nested spread that uses @connection leaves the connection's edges empty.

[jonreading81]

Update — narrower repro and code-path trace

Since filing this we've reproduced and traced the bug further. Posting the specifics in case they help.

Repro shape

Two GraphQL queries on the same page:

• Query A (non-deferred, resolves quickly):

  query A { viewer { me { hasProFeaturesTrial } } }

• Query B (deferred fragment reading a deeper field on the same shared record):

  query B { viewer { ...ChildFrag_viewer @defer } }
  
  fragment ChildFrag_viewer on Viewer {
      me { commentsReceived(first: 4) { edges { … } } }
  }

Both are preloaded from the same TanStack Router loader. Query A finishes and writes viewer.me with hasProFeaturesTrial. Query B's initial (non-deferred) chunk arrives; usePreloadedQuery(B) unblocks and returns a viewer ref, which the parent passes to a child that calls useFragment(ChildFrag_viewer, viewerRef).

At that point:

• The viewer.me record IS in the store (populated by Query A) — but only with hasProFeaturesTrial.
• viewer.me.commentsReceived is not in the store — Query B's deferred chunk for ChildFrag_viewer hasn't landed yet.
• useFragment does NOT suspend. It returns { viewer, me, commentsReceived: undefined } and the consumer crashes on the next dereference.

Traced code path (relay-runtime + react-relay 21.0.1)

We instrumented the consumer with a document.title side-channel probe and captured this from a Playwright trace: on the first render of the child, viewerRef.__fragments contained only a subset of the parent query's spread names — ChildFrag_viewer was NOT present. On a later render (after more deferred chunks arrived), it contained all of them.

Following that thread through Relay:

1. getSingularSelector(fragment, item) in RelayModernSelector.js reads item.__fragments[fragment.name]. When that key is absent, the function returns null.
2. getFragmentState(env, null) in useFragmentInternal_CURRENT.js:279 returns { kind: 'bailout' }.
3. isMissingData(state) in the same file (line 32) returns false unconditionally for bailout.
4. The suspense branch at line 412 (if (isMissingData(state)) { … throw pendingPromise }) never fires.
5. The consumer receives whatever's in the store — including undefined for the deferred field — and crashes downstream.

Why we think this is the root cause

bailout is used for two semantically different situations that need different handling:

• A) Parent didn't spread this fragment at all — legitimate no-op; returning empty/undefined data is correct.
• B) Parent DID spread this fragment @defer but the deferred chunk hasn't arrived yet — should suspend on the pending operation.

Currently both fall into the same bailout code path with no way to tell them apart at the fragment-consumer level.

A possible fix: at getSingularSelector (or in getFragmentState), if the fragment name is absent from __fragments, check whether the fragment name appears in the fragment ref's owner query's compiled AST as a deferred spread. If yes → return a pending state that triggers suspension via the owner's active-request promise. If no → the existing bailout is correct.

Caveats

Our investigation isn't 100% closed. The invariant at useFragmentInternal_CURRENT.js:311 should fire when fragmentRef != null && fragmentSelector == null, but doesn't in our repro — so the exact sequence of getSingularSelector → bailout may be slightly different from what we've reconstructed. But the observation stands: useFragment returns partial data and doesn't suspend when the deferred chunk for its own fragment is still in flight.

Workaround we shipped

Field-level guards at every read:

// BAD — deferred field can be undefined
const cloudcast = useFragment(CloudcastFrag, ref);
if (!cloudcast) return null;
return cloudcast.owner.username;

// GOOD — guard the specific field the deferred chunk will populate
if (!cloudcast?.owner) return null;
return cloudcast.owner.username;

Not a great pattern to have to remember across the whole codebase; happy to help test any upstream fix.

[jonreading81]

Follow-up on the code-path trace above — we've kept digging and think the previous hypothesis (getSingularSelector → bailout → isMissingData: false) is likely wrong for our specific manifestation, or at best incomplete.

Re-examining our own evidence: our probe caught useFragment returning data with a deferred field as undefined (viewer present, viewer.me present via a sibling query, viewer.me.commentsReceived undefined). If the bailout path had fired, useFragment would have returned null for the whole fragment (or the invariant at useFragmentInternal_CURRENT.js:391 would have thrown). Neither happened.

So the actual failing path is #2 from our earlier comment — fragmentSelector was valid, the reader correctly marked isMissingData: true for the missing deferred field, but getPendingOperationsForFragment returned null and no suspension fired. Which means one of:

• getPromiseForActiveRequest returned null because the operation's activeState was already inactive (or the request removed from _operationExecutions) by the time useFragment read
• OR the operationTracker.getPendingOperationsAffectingOwner fallback also returned null

Our setup is a client-side SSR replay: a captured deferred response arrives as one microtask, we synchronously emit sink.next(chunk) per chunk and then sink.complete(). If subscriber notifications queue re-renders but React batches them past the end of the microtask, useFragment sees the store snapshot AFTER sink.complete fired — operation completed, no pending promise, no suspend, isMissingData: true still because... actually this doesn't fully add up either, since writes are synchronous. Which is exactly why we're not sure of the mechanism.

Leaving the comment above intact rather than editing it — the code-path trace is still accurate about how the bailout branch works in general, it's just not what's firing in our case.

Happy to build a minimal repro if that would help.

[jonreading81]

Second update — we tried to reproduce the bug in isolation and it did not fire. Sharing the negative result because it substantially narrows where the actual bug lives.

Isolated repro against Relay 21.0.1

Built a jest test that mirrors the production shape exactly:

• Two queries against the same schema:
  • SiblingQuery { viewer { me { id, username } } } — non-deferred, resolves first
  • DeferredParentQuery { viewer { ...DeferredFragment @defer } } where DeferredFragment reads me { uploadLimits { tracksPublishRemaining } }
• Sibling completes first, writing viewer.me with a subset of its fields to the store
• Then the deferred query's initial (non-deferred) chunk arrives (just viewer shell), followed by the deferred payload with uploadLimits
• Both queries share a viewer.me User record — the deferred fragment reads fields the sibling didn't fetch

Real Environment + Network + Store (not createMockEnvironment), real loadQuery + usePreloadedQuery (matches our production useSerializableQuery flow), useFragment reads the deferred fragment inside a <Suspense> boundary.

Result: renderPhases: ['ok:5'] — useFragment correctly suspended during the deferred gap and only rendered once complete data was available. No partial-data window observed.

What this means

The core interaction of useFragment + @defer + a sibling-populated shared record works correctly in Relay 21.0.1. Which means the bug we see in production must involve something the isolated test doesn't reproduce.

Our SSR replay layer is the prime suspect: on the server we accumulate all chunks into an array via Observable.from(fetch).do({next}) + .finally(resolve), and on the client the response replay pipes them into the sink in one synchronous for-loop followed immediately by sink.complete(). That timing (batched sink.next + immediate complete, likely all in the same microtask) is quite different from how Relay's own tests exercise @defer (chunks arriving across separate observable emissions with React re-renders in between).

Suspected mechanism now: sink.complete() fires → _complete → cancel() → operation deleted from _operationExecutions → subsequent useFragment read finds isMissingData: true but getPromiseForActiveRequest returns null (no active operation) → no suspend → partial data returned.

We're going to investigate our own replay code first. Will follow up if we prove that's the mechanism, and either fix it in our layer or come back here with a narrower Relay-side finding.

Happy to share the isolated repro test file if useful — it's ~200 lines using real Environment + a controllable Sink per query, no test-utils mocking.

[jonreading81]

Update — root cause traced

We've traced the exact mechanism behind the correlation-miss between useFragment and the still-live owner query. It's two overlapping windows in fetchQueryInternal.js + useFragmentInternal:

Window 1 — requestCache teardown between Suspense render passes

getObservableForCachedRequest's cleanup runs when subscriber count on the cached-request subject hits 0:

if (requestSubscription != null && cachedRequestInstance.subject.getObserverCount() === 0) {
    requestSubscription.unsubscribe();
    requestCache["delete"](cachedRequest.identifier);
}

Under SSR + React 19 streaming Suspense, subscribers to an @defer'd query's subject briefly hit 0 between render passes (a suspended subtree unmounts on throw, before its retry re-subscribes). This cleanup fires, the fetch is unsubscribed, the requestCache entry is wiped — while deferred chunks are still in flight. On the retry, useFragment reads partial data, getPromiseForActiveRequest returns null because the cache is empty, and getPendingOperationsForFragment also returns null because the OperationTracker doesn't know about the operation either (nothing else writes to the fragment owner's records). useFragment returns partial data. Consumer crashes on .owner/.edges/etc.

Window 2 — First-render, before the loader's fetch populates requestCache

The loader's fetchQuery(...).subscribe(...) has been called but the start callback that writes to requestCache hasn't yet fired when React's first render pass runs. useFragment reads on that same render tick, finds no cache entry, returns partial data.

Trace evidence

Instrumented getPromiseForActiveRequest + getPendingOperationsForFragment + useFragmentInternal_EXPERIMENTAL and logged from SSR. For one fragment across 10 render attempts of the same subtree:

Attempt	isMissingData	requestCache has owner?	isRequestActive?	getPendingOperationsAffectingOwner	Result
1	true	false (cache not yet populated)	false	null	partial data → crash
2–5	true	true	true	null	suspend correctly
6	true	false (cache cleared mid-defer)	false	null	partial data → crash
7–8	true	true	true	null	suspend correctly
9	true	false (cache cleared mid-defer)	false	null	partial data → crash

Attempts 1, 6 and 9 correspond to the two windows above. getPendingOperationsAffectingOwner(owner) returns null throughout because nothing else writes to the owner record — only the operation itself would, and its records aren't updated between chunks.