Skip to content

Keep Query collection errors visible until retry succeeds - #1940

Open
KyleAMathews wants to merge 5 commits into
mainfrom
codex/issue-539-error-retry
Open

KyleAMathews wants to merge 5 commits into
mainfrom
codex/issue-539-error-retry

Conversation

@KyleAMathews

@KyleAMathews KyleAMathews commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

🎯 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.

@coderabbitai

coderabbitai Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

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 85a92c0 and e3fad0d.

📒 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 name Status Explanation Resolution
Docstring Coverage ⚠️ Warning 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 … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the primary change: Query collection errors remain visible until a retry succeeds.
Description check ✅ Passed The 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 ✅ Passed Issue [#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 ✅ Passed The 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.

@pkg-pr-new

pkg-pr-new Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
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

@github-actions

Copy link
Copy Markdown
Contributor

Size Change: 0 B

Total Size: 174 kB

ℹ️ View Unchanged
Filename Size
packages/db/dist/esm/client.js 3.7 kB
packages/db/dist/esm/collection-options.js 236 B
packages/db/dist/esm/collection/change-events.js 1.45 kB
packages/db/dist/esm/collection/changes.js 2.41 kB
packages/db/dist/esm/collection/cleanup-queue.js 794 B
packages/db/dist/esm/collection/events.js 481 B
packages/db/dist/esm/collection/index.js 4.46 kB
packages/db/dist/esm/collection/indexes.js 2.03 kB
packages/db/dist/esm/collection/lifecycle.js 2.69 kB
packages/db/dist/esm/collection/mutations.js 2.61 kB
packages/db/dist/esm/collection/state.js 8.32 kB
packages/db/dist/esm/collection/subscription.js 8.81 kB
packages/db/dist/esm/collection/sync.js 5.09 kB
packages/db/dist/esm/collection/transaction-metadata.js 144 B
packages/db/dist/esm/deferred.js 207 B
packages/db/dist/esm/errors.js 5.49 kB
packages/db/dist/esm/event-emitter.js 964 B
packages/db/dist/esm/index.js 3.88 kB
packages/db/dist/esm/indexes/auto-index.js 824 B
packages/db/dist/esm/indexes/base-index.js 1.21 kB
packages/db/dist/esm/indexes/basic-index.js 2.1 kB
packages/db/dist/esm/indexes/btree-index.js 2.29 kB
packages/db/dist/esm/indexes/index-registry.js 820 B
packages/db/dist/esm/indexes/reverse-index.js 376 B
packages/db/dist/esm/live-query-adapter.js 318 B
packages/db/dist/esm/live-query-observer.js 3.69 kB
packages/db/dist/esm/live-query-options.js 731 B
packages/db/dist/esm/live-query-window-controller.js 4.37 kB
packages/db/dist/esm/local-only.js 989 B
packages/db/dist/esm/local-storage.js 2.17 kB
packages/db/dist/esm/optimistic-action.js 359 B
packages/db/dist/esm/paced-mutations.js 702 B
packages/db/dist/esm/proxy.js 3.32 kB
packages/db/dist/esm/query/builder/clone-query.js 766 B
packages/db/dist/esm/query/builder/functions.js 1.45 kB
packages/db/dist/esm/query/builder/index.js 6.82 kB
packages/db/dist/esm/query/builder/query-ir.js 116 B
packages/db/dist/esm/query/builder/ref-proxy-identity.js 198 B
packages/db/dist/esm/query/builder/ref-proxy.js 1.35 kB
packages/db/dist/esm/query/builder/wrapper-identity.js 221 B
packages/db/dist/esm/query/compiler/evaluators.js 2.06 kB
packages/db/dist/esm/query/compiler/expressions.js 603 B
packages/db/dist/esm/query/compiler/group-by.js 4.16 kB
packages/db/dist/esm/query/compiler/index.js 9.1 kB
packages/db/dist/esm/query/compiler/joins.js 2.99 kB
packages/db/dist/esm/query/compiler/lazy-targets.js 1.13 kB
packages/db/dist/esm/query/compiler/order-by.js 1.99 kB
packages/db/dist/esm/query/compiler/parent-routes.js 319 B
packages/db/dist/esm/query/compiler/query-equivalence.js 455 B
packages/db/dist/esm/query/compiler/route-metadata.js 1.24 kB
packages/db/dist/esm/query/compiler/select.js 1.59 kB
packages/db/dist/esm/query/effect.js 4.98 kB
packages/db/dist/esm/query/equality-value-identity.js 591 B
packages/db/dist/esm/query/expression-helpers.js 1.45 kB
packages/db/dist/esm/query/ir-stable-identity.js 4.22 kB
packages/db/dist/esm/query/ir.js 1.7 kB
packages/db/dist/esm/query/live-query-collection.js 391 B
packages/db/dist/esm/query/live/bucket-facade-adapter.js 2.73 kB
packages/db/dist/esm/query/live/collection-config-builder.js 6.52 kB
packages/db/dist/esm/query/live/collection-registry.js 264 B
packages/db/dist/esm/query/live/collection-subscriber.js 2.16 kB
packages/db/dist/esm/query/live/graph-scheduler.js 303 B
packages/db/dist/esm/query/live/internal.js 145 B
packages/db/dist/esm/query/live/materialized-pipeline.js 2.32 kB
packages/db/dist/esm/query/live/ordered-source-loader.js 4.47 kB
packages/db/dist/esm/query/live/subset-demand-controller.js 1.67 kB
packages/db/dist/esm/query/live/utils.js 1.2 kB
packages/db/dist/esm/query/optimizer.js 2.93 kB
packages/db/dist/esm/query/query-once.js 359 B
packages/db/dist/esm/query/runtime-reference-identity.js 630 B
packages/db/dist/esm/query/subset-dedupe.js 497 B
packages/db/dist/esm/scheduler.js 1.14 kB
packages/db/dist/esm/SortedMap.js 1.3 kB
packages/db/dist/esm/strategies/debounceStrategy.js 331 B
packages/db/dist/esm/strategies/queueStrategy.js 488 B
packages/db/dist/esm/strategies/throttleStrategy.js 386 B
packages/db/dist/esm/sync-persistence.js 530 B
packages/db/dist/esm/transactions.js 3.73 kB
packages/db/dist/esm/utils.js 1.21 kB
packages/db/dist/esm/utils/array-utils.js 270 B
packages/db/dist/esm/utils/browser-polyfills.js 304 B
packages/db/dist/esm/utils/btree.js 4.51 kB
packages/db/dist/esm/utils/callbacks.js 174 B
packages/db/dist/esm/utils/comparison.js 1.5 kB
packages/db/dist/esm/utils/cursor.js 677 B
packages/db/dist/esm/utils/error.js 167 B
packages/db/dist/esm/utils/get-or-create.js 155 B
packages/db/dist/esm/utils/index-optimization.js 2.42 kB
packages/db/dist/esm/utils/type-guards.js 230 B
packages/db/dist/esm/utils/uuid.js 449 B
packages/db/dist/esm/virtual-props.js 360 B

compressed-size-action::db-package-size

@github-actions

Copy link
Copy Markdown
Contributor

Size Change: 0 B

Total Size: 7.97 kB

ℹ️ View Unchanged
Filename Size
packages/react-db/dist/esm/DbProvider.js 317 B
packages/react-db/dist/esm/HydrationBoundary.js 263 B
packages/react-db/dist/esm/index.js 330 B
packages/react-db/dist/esm/live-query-internals.js 282 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js 1.9 kB
packages/react-db/dist/esm/useLiveQuery.js 3.3 kB
packages/react-db/dist/esm/useLiveQueryEffect.js 355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js 820 B
packages/react-db/dist/esm/usePacedMutations.js 401 B

compressed-size-action::react-db-package-size

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify QueryCollection clearError() timing semantics

1 participant