Skip to content
Source
Sign inSign up
TanStack/db

fix: render persisted data in Suspense after client stream errors #1960

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 5 commits intomain fromrefs/pull/1960/headmerged by KyleAMathews(GitHub profile, opens in a new tab)

Changes

React Suspense now renders completed persisted query data when an opted-in client query stream fails. Previously, the hook could throw the stream error or return empty rows before restore completed. This follows up on #1955.

Apps still select initialRender: { strategy: 'network-first' } on each eager persisted source Collection. Every query source must opt in. useLiveSuspenseQuery still prefers Collection readiness until the network deadline. If the client stream fails, the hook waits for every persisted restore. It then renders the derived query result, including a completed empty result. Network sync continues.

The stream can fail before the hook mounts, while restore is pending, or after restore. The observer recognizes the current failed client record in each case. The hook keeps Suspense active until the observer permits fallback.

Errors and retries

A derived-query failure is not a network fallback signal. It reaches the React ErrorBoundary, even if a client stream also failed. An unconfigured query still reports its client error, including an undefined rejection.

The hook saves definitive initial-render errors across React render retries. A replacement client record does not inherit an old error. Collection cleanup invalidates late errors from the old sync run. Collection readiness clears saved errors.

This PR keeps the existing deadline and all-source opt-in rule. It does not change ordinary useLiveQuery row publication. A mixed query with an unconfigured source still has persistedStatus: 'unavailable'.

Persisted readiness does not prove current authorization. Apps must isolate persisted storage by user or tenant. Apps must block the view separately if a policy denial must hide cached rows.

Verification

  • The persisted-readiness oracle passed 35 tests. Its new cases cover empty and nonempty restore before and after stream failure.
  • The oracle also covers a failed stream before observer construction. That case failed before this repair.
  • React passed 300 runtime tests. Its new cases cover stream failure before mount, before restore, and after restore.
  • React keeps derived-query failures on the ErrorBoundary and preserves client retry and cleanup behavior.
  • The observer passed 54 tests. Solid passed 48 focused tests.
  • TypeScript checks passed for @tanstack/db, React DB, and SQLite persistence core. Formatting and changed-file lint checks passed.
  • Full-package Vitest typecheck still reports cross-package rootDir errors. Direct TypeScript project checks passed with the repository root as rootDir.

The existing Solid duplicate-observer optimization remains separate work. The reported reportUpstreamError startup side effect did not reproduce through the source sync callback.

✅ Checklist

  • I have tested this code locally with pnpm test.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • Bug Fixes
    • When a client query stream fails during network-first initial rendering, completed persisted data can still be displayed.
    • Failures in derived queries continue to reach React Error Boundaries, including when a client query stream has also failed.
    • Initial-render errors are isolated between database clients and cleared when a collection restarts or is cleaned up, preventing stale failures from affecting fresh queries.
    1. Review in Change Stack →

      Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Advanced

      Run ID: 4dc74310-b01d-44ef-8f70-d12aebb37ca7

      📥 Commits

      Reviewing files that changed from the base of the PR and between 7eeff97c53fe589549dd0cf9bb7f0ed6acdf6125 and 365732246e0bc99a8a650d982e3091471f72056a.

      📒 Files selected for processing (8)
      • .changeset/fix-react-persisted-query-error.md
      • docs/contributing/glossary.md
      • docs/contributing/oracle-coverage.md
      • packages/db-sqlite-persistence-core/tests/persisted-readiness-oracle.test.ts
      • packages/db/src/live-query-observer.ts
      • packages/react-db/src/useLiveSuspenseQuery.ts
      • packages/react-db/tests/useLiveSuspenseQuery-recovery.test.tsx
      • packages/react-db/tests/useLiveSuspenseQuery.test.tsx
      🚧 Files skipped from review as they are similar to previous changes (1)
      • .changeset/fix-react-persisted-query-error.md

      Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.


      📝 Walkthrough

      Walkthrough

      The observer now treats a failed client query stream as a network failure during initial rendering when persisted data is complete. The React hook tracks eligible preload failures by collection and client, and surfaces them until readiness or cleanup.

      Changes

      Initial-render readiness and React error handling

      Layer / File(s)Summary
      Persisted readiness and stream failures
      packages/db/src/live-query-observer.ts, packages/db-sqlite-persistence-core/tests/persisted-readiness-oracle.test.ts, docs/contributing/oracle-coverage.md
      The observer can treat a failed current client query stream as ready when persisted data is complete. Oracle tests cover empty and nonempty restores, failure timing, and derived-query failures. Coverage documentation describes these cases.
      React preload error tracking and recovery
      packages/react-db/src/useLiveSuspenseQuery.ts, packages/react-db/tests/useLiveSuspenseQuery*.test.tsx, docs/contributing/glossary.md, .changeset/fix-react-persisted-query-error.md
      The hook tracks eligible preload failures by collection and client, discards stale records, and clears records on readiness or cleanup. Tests cover error-boundary behavior, client isolation, replacement queries, and cleanup and restart. The glossary and changeset describe the failure distinctions and release updates.

      Priority: ⬇️ Low

      Estimated code review effort: 3 (Moderate) | ~25 minutes

      Change: Bug fix

      Merge Risk: ⚪ Minimal · up to 36573

      The change enables completed persisted data to render after client-stream failures while preserving query-error handling. No concrete merge-blocking issue is identified; merge after normal checks pass.

      Security Architecture Review

      Security architecture risk: 🔵 Low · up to 36573

      The change preserves important client-isolation and cleanup safeguards. No security vulnerability was established, but rendering persisted data after a failed client request depends on data remaining authorized for the current user. That assumption and one request-recovery edge remain incompletely established.

      Retained concerns No architecture-level concerns identified.

      Security review details

      Security Blast Radius

      • inferred — The demonstrated exposure is rendering rows already held by opted-in persisted source collections after the matching client stream fails. No cross-tenant, cross-service, or privileged infrastructure access was established; broader exposure depends on application cache ownership and identity transitions.

      Trust Boundaries and Controls

      • inferred — Current-record identity and per-client error storage constrain failure attribution, but do not themselves authorize persisted rows. Whether permission-denied streams can cause unauthorized stale-data rendering remains unresolved because neither their production error mapping nor identity-transition invalidation was established.

      Resilience and Maintainability Implications

      • inferred — A client-scoped preload need not create a query record when SSR streaming is disabled. If its cached rejection has no record identity, registering a first pending record does not invalidate that rejection, so a boundary reset can replay the old failure until readiness or cleanup clears it. This is a bounded recovery edge, not an established security vulnerability, and its PR-base attribution remains uncertain.

      Hardening Proposals

      • proposed — Define the authorization assumptions of persisted fallback explicitly: restored rows should remain scoped to the active identity, and applications should distinguish permission revocation from recoverable transport failure where stale-data rendering is inappropriate.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (3 skipped: …Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Title check✅ PassedThe title clearly and concisely describes the primary change: rendering persisted data in Suspense after client stream errors.
      Description check✅ PassedThe description includes the required Changes, Checklist, and Release Impact sections. It explains the behavior, error handling, testing, and changeset. The pnpm test checklist item remains unchecked,…
      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (3 skipped: 3 unsupported.)

      • Fix all pre-merge checks with AI
      ✨ Finishing Touches 💡 1
      📝 Generate docstrings 💡
      • Commit to this branch
      • Create a new PR
      🧪 Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR
      • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Autopilot is currently an internal CodeRabbit preview.


      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. More templates

      @tanstack/angular-db

      npm i https://pkg.pr.new/@tanstack/angular-db@1960

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1960

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1960

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1960

      @tanstack/db

      npm i https://pkg.pr.new/@tanstack/db@1960

      @tanstack/db-ivm

      npm i https://pkg.pr.new/@tanstack/db-ivm@1960

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1960

      @tanstack/electric-db-collection

      npm i https://pkg.pr.new/@tanstack/electric-db-collection@1960

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1960

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1960

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1960

      @tanstack/offline-transactions

      npm i https://pkg.pr.new/@tanstack/offline-transactions@1960

      @tanstack/powersync-db-collection

      npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1960

      @tanstack/query-db-collection

      npm i https://pkg.pr.new/@tanstack/query-db-collection@1960

      @tanstack/react-db

      npm i https://pkg.pr.new/@tanstack/react-db@1960

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1960

      @tanstack/react-router-with-db

      npm i https://pkg.pr.new/@tanstack/react-router-with-db@1960

      @tanstack/rxdb-db-collection

      npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1960

      @tanstack/solid-db

      npm i https://pkg.pr.new/@tanstack/solid-db@1960

      @tanstack/svelte-db

      npm i https://pkg.pr.new/@tanstack/svelte-db@1960

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1960

      @tanstack/trailbase-db-collection

      npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1960

      @tanstack/vue-db

      npm i https://pkg.pr.new/@tanstack/vue-db@1960

      commit: 3657322

    3. Size Change: +106 B (+0.06%)

      Total Size: 175 kB

      📦 View Changed
      FilenameSizeChange
      packages/db/dist/esm/live-query-observer.js4.82 kB+106 B (+2.25%)
      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/client.js3.7 kB
      packages/db/dist/esm/collection-options.js236 B
      packages/db/dist/esm/collection/change-events.js1.45 kB
      packages/db/dist/esm/collection/changes.js2.41 kB
      packages/db/dist/esm/collection/cleanup-queue.js822 B
      packages/db/dist/esm/collection/events.js481 B
      packages/db/dist/esm/collection/index.js4.46 kB
      packages/db/dist/esm/collection/indexes.js2.06 kB
      packages/db/dist/esm/collection/lifecycle.js2.69 kB
      packages/db/dist/esm/collection/mutations.js2.61 kB
      packages/db/dist/esm/collection/state.js8.38 kB
      packages/db/dist/esm/collection/subscription.js8.81 kB
      packages/db/dist/esm/collection/sync.js5.09 kB
      packages/db/dist/esm/collection/transaction-metadata.js144 B
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/errors.js5.49 kB
      packages/db/dist/esm/event-emitter.js964 B
      packages/db/dist/esm/index.js3.94 kB
      packages/db/dist/esm/indexes/auto-index.js841 B
      packages/db/dist/esm/indexes/base-index.js1.26 kB
      packages/db/dist/esm/indexes/basic-index.js2.05 kB
      packages/db/dist/esm/indexes/btree-index.js2.33 kB
      packages/db/dist/esm/indexes/index-registry.js820 B
      packages/db/dist/esm/indexes/reverse-index.js376 B
      packages/db/dist/esm/live-query-adapter.js318 B
      packages/db/dist/esm/live-query-options.js731 B
      packages/db/dist/esm/live-query-window-controller.js4.4 kB
      packages/db/dist/esm/local-only.js989 B
      packages/db/dist/esm/local-storage.js2.17 kB
      packages/db/dist/esm/optimistic-action.js359 B
      packages/db/dist/esm/paced-mutations.js702 B
      packages/db/dist/esm/persisted-readiness.js195 B
      packages/db/dist/esm/proxy.js3.32 kB
      packages/db/dist/esm/query/builder/clone-query.js766 B
      packages/db/dist/esm/query/builder/functions.js1.45 kB
      packages/db/dist/esm/query/builder/index.js6.82 kB
      packages/db/dist/esm/query/builder/query-ir.js116 B
      packages/db/dist/esm/query/builder/ref-proxy-identity.js198 B
      packages/db/dist/esm/query/builder/ref-proxy.js1.35 kB
      packages/db/dist/esm/query/builder/wrapper-identity.js221 B
      packages/db/dist/esm/query/compiler/evaluators.js2.06 kB
      packages/db/dist/esm/query/compiler/expressions.js603 B
      packages/db/dist/esm/query/compiler/group-by.js4.16 kB
      packages/db/dist/esm/query/compiler/index.js9.1 kB
      packages/db/dist/esm/query/compiler/joins.js2.99 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js1.13 kB
      packages/db/dist/esm/query/compiler/order-by.js1.99 kB
      packages/db/dist/esm/query/compiler/parent-routes.js319 B
      packages/db/dist/esm/query/compiler/query-equivalence.js455 B
      packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB
      packages/db/dist/esm/query/compiler/select.js1.59 kB
      packages/db/dist/esm/query/effect.js4.98 kB
      packages/db/dist/esm/query/equality-value-identity.js591 B
      packages/db/dist/esm/query/expression-helpers.js1.45 kB
      packages/db/dist/esm/query/ir-stable-identity.js4.22 kB
      packages/db/dist/esm/query/ir.js1.7 kB
      packages/db/dist/esm/query/live-query-collection.js391 B
      packages/db/dist/esm/query/live/bucket-facade-adapter.js2.73 kB
      packages/db/dist/esm/query/live/collection-config-builder.js6.58 kB
      packages/db/dist/esm/query/live/collection-registry.js264 B
      packages/db/dist/esm/query/live/collection-subscriber.js2.16 kB
      packages/db/dist/esm/query/live/graph-scheduler.js303 B
      packages/db/dist/esm/query/live/internal.js145 B
      packages/db/dist/esm/query/live/materialized-pipeline.js2.32 kB
      packages/db/dist/esm/query/live/ordered-source-loader.js4.47 kB
      packages/db/dist/esm/query/live/subset-demand-controller.js1.67 kB
      packages/db/dist/esm/query/live/utils.js1.2 kB
      packages/db/dist/esm/query/optimizer.js2.93 kB
      packages/db/dist/esm/query/query-once.js359 B
      packages/db/dist/esm/query/runtime-reference-identity.js630 B
      packages/db/dist/esm/query/subset-dedupe.js497 B
      packages/db/dist/esm/scheduler.js1.14 kB
      packages/db/dist/esm/SortedMap.js1.63 kB
      packages/db/dist/esm/strategies/debounceStrategy.js331 B
      packages/db/dist/esm/strategies/queueStrategy.js488 B
      packages/db/dist/esm/strategies/throttleStrategy.js386 B
      packages/db/dist/esm/sync-persistence.js530 B
      packages/db/dist/esm/transactions.js3.73 kB
      packages/db/dist/esm/utils.js1.22 kB
      packages/db/dist/esm/utils/array-utils.js270 B
      packages/db/dist/esm/utils/browser-polyfills.js304 B
      packages/db/dist/esm/utils/btree.js3.01 kB
      packages/db/dist/esm/utils/callbacks.js174 B
      packages/db/dist/esm/utils/comparison.js1.59 kB
      packages/db/dist/esm/utils/cursor.js677 B
      packages/db/dist/esm/utils/error.js167 B
      packages/db/dist/esm/utils/get-or-create.js155 B
      packages/db/dist/esm/utils/index-optimization.js2.42 kB
      packages/db/dist/esm/utils/type-guards.js230 B
      packages/db/dist/esm/utils/uuid.js449 B
      packages/db/dist/esm/virtual-props.js360 B
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 8.06 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/react-db/dist/esm/DbProvider.js317 B
      packages/react-db/dist/esm/HydrationBoundary.js263 B
      packages/react-db/dist/esm/index.js330 B
      packages/react-db/dist/esm/live-query-internals.js282 B
      packages/react-db/dist/esm/useLiveInfiniteQuery.js1.93 kB
      packages/react-db/dist/esm/useLiveQuery.js3.3 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js355 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js881 B
      packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size

Sign in to join this conversation.