Skip to content
Source
Sign inSign up
TanStack/db

Keep Query collection errors visible until retry succeeds #1940

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 5 commits intomain fromrefs/pull/1940/headmerged 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 test suite.

🚀 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. 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: 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.md
      • docs/contributing/oracle-coverage.md
      • docs/contributing/oracle-reviews/pr-1940-held-error-recency.md
      • docs/guides/error-handling.md
      • packages/query-db-collection/src/query.ts
      • packages/query-db-collection/tests/ownership-lifecycle.oracle.test.ts
      🚧 Files skipped from review as they are similar to previous changes (1)
      • docs/contributing/oracle-coverage.md

      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

      Layer / File(s)Summary
      Track errors across retry attempts
      packages/query-db-collection/src/query.ts
      clearError() no longer resets lastError or errorCount before refetch. Fetch errors are counted from new idle Query error updates, instead of timestamps or error object identity.
      Apply results without clearing newer errors
      packages/query-db-collection/src/query.ts
      A successful result clears errors only when it is not fetching and no newer error was recorded during application. Application failures advance the error revision.
      Validate and describe retry outcomes
      packages/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.md
      Oracle tests cover held retries, application failures, persisted-scan races, repeated errors, and intermediate retry attempts. Documentation and the changeset describe retry outcomes and mutation-handler fetch-boundary timing.

      Priority: ⬇️ Low

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

      Change: Bug fix · Severity of issue fixed: Low

      Merge Risk: ⚪ Minimal · up to e3fad

      Query 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 e3fad

      The 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

      • inferred — The demonstrated exposure remains the existing caller-configured Query Collection and its public recovery state. clearError accepts no new input and invokes the existing refetch dependency; the inspected change does not demonstrate broader data access or additional authority. Deployment-specific tenant and service exposure was not supplied.

      Trust Boundaries and Controls

      • observed — Query-function results continue through the existing Query-to-Collection application boundary. The observer's current Query is checked for post-write authority, and application validates rows before constructing collection mutations. Error-recovery reporting is downstream of application rather than an alternative write path.

      Resilience and Maintainability Implications

      • observed — Failure containment uses per-query application identity and cancellation. Replacing or cleaning up an application invokes rollback and aborts its controller; asynchronous completion can update error state only while its promise is current. Revision equality additionally prevents an older application from clearing a newer recorded failure.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring 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 …Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely describes the primary change: Query collection errors remain visible until a retry succeeds.
      Description check✅ PassedThe description covers the change, motivation, behavior, testing, release impact, known coverage limits, and changeset. It follows the required template. The unchecked full-suite test item is clearly …
      Linked Issues check✅ PassedIssue [#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 …
      Out of Scope Changes check✅ PassedThe implementation, ownership tests, Query collection documentation, error-handling documentation, oracle coverage record, review record, and changeset all support Issue [#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.)

      • 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

      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@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@1940

      commit: e3fad0d

    3. Size Change: 0 B

      Total Size: 174 kB

      ℹ️ 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.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
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 7.97 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.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
      compressed-size-action::react-db-package-size

Sign in to join this conversation.