Keep Query collection errors visible until retry succeeds #1940
main fromrefs/pull/1940/head·merged by KyleAMathews(GitHub profile, opens in a new tab) 🎯 Changes#
clearError() now keeps the previous error visible until a successful Query result applies to the Collection. A terminal failed retry records another consecutive failure. Intermediate Query retry attempts do not recount the old error. This prevents the UI from appearing recovered before the rows are available.
const retry = collection.utils.clearError()
collection.utils.isError // true while the retry is pending
collection.utils.lastError // the previous error
await retry // a normally completed retry has applied its rows
collection.utils.isError // false after successful application
Previously, clearError() set lastError to undefined and errorCount to zero before it started the refetch. A cached success notification or successful fetch could also clear an error before row application finished. The retry now starts first, and successful application clears the public error fields. A terminal failure advances the count, even when the same error returns at clock time zero.
The ownership oracle checks initial, background, and Collection application failures. It holds a retry before fetch settlement and after fetch settlement, before row application. It also checks a repeated error object at clock time zero and an intermediate automatic Query retry. Each new case failed on the previous patch and passes now. The production diff adds eight net lines.
During a mutation handler, clearError() can resolve at the documented fetch boundary before application clears the error. The oracle does not cover concurrent tracked Queries or deferred application.
✅ Checklist#
- The full Query collection package suite passed: 889 tests across 30 files, with no type errors.
- I ran the full
pnpm testsuite.
🚀 Release Impact#
- This change affects published code, and I added a changeset.
- This change is docs/CI/dev-only (no release).
Fixes #539.
Summary by CodeRabbit#
- Bug Fixes
- Query collection errors now remain visible while a retry is pending. A failed retry is counted as another consecutive failure; a successfully applied result clears the error and resets the count.
- An older result arriving after a newer failure no longer incorrectly clears the newer error.
- Documentation
- Updated error-handling guidance to clarify when errors clear and how retries behave, including during mutation handlers.
- 1
More templates
- todos
- offline-first-electron
- @tanstack/db-example-react-next-ssr-e2e
- tanstack-start-example-basic
- @tanstack/db-example-paced-mutations-demo
- tanstack-start-db-projects-example
- @tanstack/db-example-react-start-ssr-e2e
- @tanstack/db-example-react-todo
- offline-transactions-react-native
- shopping-list-react-native
- @tanstack/db-example-solid-todo
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1940@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1940@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1940@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1940@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1940@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1940@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1940@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1940@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1940@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1940@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1940@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1940@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1940@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1940@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1940@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1940@tanstack/react-router-with-db
npm i https://pkg.pr.new/@tanstack/react-router-with-db@1940@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1940@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1940@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1940@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1940@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1940@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1940commit:
e3fad0dSize Change: 0 B
Total Size: 174 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size 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.js794 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.03 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.32 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.88 kB packages/db/dist/esm/indexes/auto-index.js824 B packages/db/dist/esm/indexes/base-index.js1.21 kB packages/db/dist/esm/indexes/basic-index.js2.1 kB packages/db/dist/esm/indexes/btree-index.js2.29 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-observer.js3.69 kB packages/db/dist/esm/live-query-options.js731 B packages/db/dist/esm/live-query-window-controller.js4.37 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/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.52 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.3 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.21 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.js4.51 kB packages/db/dist/esm/utils/callbacks.js174 B packages/db/dist/esm/utils/comparison.js1.5 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 Size Change: 0 B
Total Size: 7.97 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size 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.9 kB packages/react-db/dist/esm/useLiveQuery.js3.3 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js820 B packages/react-db/dist/esm/usePacedMutations.js401 B KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
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:
e462cef1-2d07-4b9a-92a6-c8e5a2e46af2📥 Commits
Reviewing files that changed from the base of the PR and between 85a92c0f1634416df91c326d77cc2281cdc32940 and e3fad0d8e4f7a419c8898b802469f424c9accce7.
📒 Files selected for processing (6)
docs/collections/query-collection.mddocs/contributing/oracle-coverage.mddocs/contributing/oracle-reviews/pr-1940-held-error-recency.mddocs/guides/error-handling.mdpackages/query-db-collection/src/query.tspackages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 0 remain after this review.
📝 Walkthrough
Walkthrough#
clearError()retains the current error while a refetch is pending. A successful result clears the error after it applies to the Collection. A failed retry records another failure. Tests and documentation cover these outcomes and the timing of mutation-handler promises.Changes#
Query error retry
packages/query-db-collection/src/query.tsclearError()no longer resetslastErrororerrorCountbefore refetch. Fetch errors are counted from new idle Query error updates, instead of timestamps or error object identity.packages/query-db-collection/src/query.tspackages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts,docs/guides/error-handling.md,docs/collections/query-collection.md,docs/contributing/oracle-coverage.md,docs/contributing/oracle-reviews/pr-1940-held-error-recency.md,.changeset/fix-query-error-retry.mdPriority: ⬇️ Low
Estimated code review effort: 3 (Moderate) | ~25 minutes
Change: Bug fix · Severity of issue fixed: Low
Merge Risk: ⚪ Minimal · up to
e3fadQuery collection errors now stay visible until a successful result is applied, and failed retries count as another failure. No concrete merge-blocking issue was identified. The remaining gaps are untested scenarios, not known bugs.
Security Architecture Review#
Security architecture risk: 🔵 Low · up to
e3fadThe retry keeps errors visible until rows are applied, reducing premature recovery signals. No expanded access or weakened validation was identified in the reviewed path. Risk remains low because callers observe changed recovery timing, while concurrent-query and deferred-application behavior are not fully demonstrated.
Retained concerns No architecture-level concerns identified.
Security review details
Security Blast Radius
Trust Boundaries and Controls
Resilience and Maintainability Implications
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
#539] requires recovery behavior that minimizes UI flicker, consistent error state, and behavior documentation.clearError()now keeps the recorded error until a successful result applies to …#539]. The changes do not int…Full details: Docstring Coverage
Explanation
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (4 skipped: 4 unsupported.)
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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