Skip to content
Source
Sign inSign up
TanStack/db

Fix error propagation from sync clients to collections #671

ClosedKyleAMathews(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromelectric-errorsopened

Summary

Fixes critical error propagation issues where errors from Electric SQL and TanStack Query weren't being propagated to collections, causing:

  1. preload() hanging indefinitely - When sync errors occurred, apps waiting for preload() would block forever
  2. Collections marked ready with no data - Collections would show status: 'ready' even when they had failed to sync any data

Changes

Electric-db-collection (packages/electric-db-collection/src/electric.ts)

  • Implement 10-second grace period before setting error status, allowing Electric's built-in retry logic to recover from transitory network issues
  • Remove premature markReady() call that was incorrectly marking collections ready before data synced
  • Clear error timer on successful recovery

Query-db-collection (packages/query-db-collection/src/query.ts)

  • Set error status immediately after TanStack Query exhausts all retry attempts
  • No grace period needed since TanStack Query handles retries internally

preload() fix (packages/db/src/collection/sync.ts)

  • Listen for status:error events and reject the promise
  • Prevents indefinite hangs when sync fails

Collection lifecycle improvements (packages/db/src/collection/)

  • Added markError() method for sync implementations to set error state
  • Made events property public (was _events private)
  • markReady() now auto-handles error recovery by transitioning through loading state (error → loading → ready)
  • Valid state transitions updated to support recovery: error can transition to idle or loading

Test plan

  • ✅ All 66 tests passing in @tanstack/electric-db-collection
  • ✅ All 58 tests passing in @tanstack/query-db-collection
  • ✅ New tests verify:
    • Error status set after 10 seconds of continuous errors (electric)
    • preload() rejects after 10 seconds of errors
    • Error timer cleared on recovery within grace period
    • Transitory errors recover naturally without setting error status

🤖 Generated with Claude Code

    1. ⚠️ No Changeset found

      Latest commit: 4b743b9c9de6101c523f77d00667606e8d8575b0

      Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

      This PR includes no changesets

      When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

      Click here to learn what changesets are, and how to add one.

      Click here if you're a maintainer who wants to add a changeset to this PR

    2. More templates

      @tanstack/angular-db

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

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/electric-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: 4b743b9

    3. Size Change: +122 B (+0.15%)

      Total Size: 81.7 kB

      FilenameSizeChange
      ./packages/db/dist/esm/collection/index.js3.31 kB+1 B (+0.03%)
      ./packages/db/dist/esm/collection/lifecycle.js1.86 kB+58 B (+3.22%)
      ./packages/db/dist/esm/collection/sync.js1.75 kB+63 B (+3.74%)
      ℹ️ View Unchanged
      FilenameSize
      ./packages/db/dist/esm/collection/change-events.js963 B
      ./packages/db/dist/esm/collection/changes.js1.01 kB
      ./packages/db/dist/esm/collection/events.js660 B
      ./packages/db/dist/esm/collection/indexes.js1.16 kB
      ./packages/db/dist/esm/collection/mutations.js2.52 kB
      ./packages/db/dist/esm/collection/state.js3.79 kB
      ./packages/db/dist/esm/collection/subscription.js1.83 kB
      ./packages/db/dist/esm/deferred.js230 B
      ./packages/db/dist/esm/errors.js3.5 kB
      ./packages/db/dist/esm/index.js1.63 kB
      ./packages/db/dist/esm/indexes/auto-index.js794 B
      ./packages/db/dist/esm/indexes/base-index.js835 B
      ./packages/db/dist/esm/indexes/btree-index.js2 kB
      ./packages/db/dist/esm/indexes/lazy-index.js1.21 kB
      ./packages/db/dist/esm/indexes/reverse-index.js577 B
      ./packages/db/dist/esm/local-only.js967 B
      ./packages/db/dist/esm/local-storage.js2.33 kB
      ./packages/db/dist/esm/optimistic-action.js294 B
      ./packages/db/dist/esm/proxy.js3.86 kB
      ./packages/db/dist/esm/query/builder/functions.js615 B
      ./packages/db/dist/esm/query/builder/index.js4.04 kB
      ./packages/db/dist/esm/query/builder/ref-proxy.js938 B
      ./packages/db/dist/esm/query/compiler/evaluators.js1.55 kB
      ./packages/db/dist/esm/query/compiler/expressions.js760 B
      ./packages/db/dist/esm/query/compiler/group-by.js2.04 kB
      ./packages/db/dist/esm/query/compiler/index.js2.19 kB
      ./packages/db/dist/esm/query/compiler/joins.js2.63 kB
      ./packages/db/dist/esm/query/compiler/order-by.js1.26 kB
      ./packages/db/dist/esm/query/compiler/select.js1.28 kB
      ./packages/db/dist/esm/query/ir.js785 B
      ./packages/db/dist/esm/query/live-query-collection.js404 B
      ./packages/db/dist/esm/query/live/collection-config-builder.js5.3 kB
      ./packages/db/dist/esm/query/live/collection-registry.js233 B
      ./packages/db/dist/esm/query/live/collection-subscriber.js1.86 kB
      ./packages/db/dist/esm/query/optimizer.js3.26 kB
      ./packages/db/dist/esm/scheduler.js1.29 kB
      ./packages/db/dist/esm/SortedMap.js1.24 kB
      ./packages/db/dist/esm/transactions.js3.05 kB
      ./packages/db/dist/esm/utils.js1.01 kB
      ./packages/db/dist/esm/utils/browser-polyfills.js365 B
      ./packages/db/dist/esm/utils/btree.js6.01 kB
      ./packages/db/dist/esm/utils/comparison.js754 B
      ./packages/db/dist/esm/utils/index-optimization.js1.73 kB
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 1.46 kB

      ℹ️ View Unchanged
      FilenameSize
      ./packages/react-db/dist/esm/index.js152 B
      ./packages/react-db/dist/esm/useLiveQuery.js1.31 kB
      compressed-size-action::react-db-package-size
    5. packages/db/src/collection/index.ts line 218
      @@ -215,4 +215,4 @@
      215215 public utils: Record<string, Fn> = {}
      216216
      217217 // Managers
      218- private _events: CollectionEventsManager
      218+ public events: CollectionEventsManager

      the manager classes are intended to be a private api, but have to be public so that they can see each other, and we can introspect them from tests. This should change it to public, but maintain the underscore on the name.

      The "public" face of the events api is a set of methods on the Collection class itself that forward to this manager.

        public _events: CollectionEventsManager
      packages/db/src/collection/lifecycle.ts lines 147 to 150
      @@ -143,3 +144,7 @@
      143144 * @private - Should only be called by sync implementations
      144145 */
      145146 public markReady(): void {
      147+ // If recovering from error, transition to loading first
      148+ if (this.status === `error`) {
      149+ this.setStatus(`loading`)
      150+ }

      I don't like this, markReady should only move you to a ready state not loading.

      We do not have a way in live queries to handle a ready => loading

      How much handling of errors and moving between states to we expect the sync implementation to do? It seems to me there are two options for a collection:

      1. handle error recovery with no braking of the synced state, as they do with a truncate, and so a markReady to go from error -> ready makes sense.
      2. catastrophic "unrecoverable" error and the sync needs to be restarted. In that case a restartSync() method that the sync handler can call that:
      • calls .cleanup(), doing a gc and moves to cleaned-up
      • then calls .startSync(), which moves to loading and finally ready once the sync marks it as such.

      Option 2 has some nuances arround subscriptions we would need to handle. Existing subscription would also need to be restarted, but we had not implemented that yet, it would be the truncate message from issue #634 proposing a refactor of the reconciliation process.

    6. @KyleAMathews what is the status of this PR? Do you plan to work through it soon or should we mark it as Draft for now?

Sign in to join this conversation.