Fix error propagation from sync clients to collections #671
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Errors from Electric SQL and TanStack Query weren't being propagated to collections, causing two critical issues: 1. `preload()` would hang indefinitely when sync errors occurred, blocking apps waiting for data 2. Collections would be marked as 'ready' even when they had no synced data, leading to empty results **Changes:** - **electric-db-collection**: Implement 10-second grace period before marking collection as errored, allowing Electric's built-in retry logic to recover from transitory network issues. Remove premature `markReady()` call that was marking collections ready with no data. - **query-db-collection**: Set error status immediately after TanStack Query exhausts retries (no grace period needed since Query handles retries internally). - **preload()**: Listen for `status:error` events and reject the promise, preventing indefinite hangs when sync fails. - **Collection lifecycle**: Add `markError()` method and make `events` public. Auto-handle error recovery in `markReady()` by transitioning through loading state (error → loading → ready). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
|
More templates
@tanstack/angular-db
@tanstack/db
@tanstack/db-ivm
@tanstack/electric-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
|
Size Change: +122 B (+0.15%) Total Size: 81.7 kB
ℹ️ View Unchanged
|
|
Size Change: 0 B Total Size: 1.46 kB ℹ️ View Unchanged
|
samwillis
requested changes
Oct 14, 2025
|
|
||
| // Managers | ||
| private _events: CollectionEventsManager | ||
| public events: CollectionEventsManager |
There was a problem hiding this comment.
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.
Suggested change
| public events: CollectionEventsManager | |
| public _events: CollectionEventsManager |
Comment on lines
+147
to
+150
| // If recovering from error, transition to loading first | ||
| if (this.status === `error`) { | ||
| this.setStatus(`loading`) | ||
| } |
There was a problem hiding this comment.
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:
- handle error recovery with no braking of the synced state, as they do with a truncate, and so a
markReadyto go fromerror -> readymakes sense. - 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 tocleaned-up - then calls
.startSync(), which moves toloadingand finallyreadyonce 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.
samwillis
reviewed
Oct 15, 2025
KyleAMathews
pushed a commit
that referenced
this pull request
Oct 20, 2025
…cerns Comprehensive analysis of GitHub issue #672 and samwillis' feedback on PR #671: - Document current error handling state across collection types - Analyze proposed first-class error tracking in CollectionLifecycleManager - Examine samwillis' concerns about error state transitions - Compare Graceful Recovery vs Catastrophic Restart models - Identify design questions around state transition validity - Propose solution path supporting both recovery patterns - Highlight backwards compatibility and testing considerations Key findings: - Query collections use closure-based error tracking - Electric collections lack error tracking entirely - Current transitions don't allow error → ready or error → loading - Live queries can't handle ready → loading transitions - Two distinct error recovery patterns needed for different scenarios 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fixes critical error propagation issues where errors from Electric SQL and TanStack Query weren't being propagated to collections, causing:
preload()hanging indefinitely - When sync errors occurred, apps waiting forpreload()would block foreverstatus: 'ready'even when they had failed to sync any dataChanges
Electric-db-collection (
packages/electric-db-collection/src/electric.ts)markReady()call that was incorrectly marking collections ready before data syncedQuery-db-collection (
packages/query-db-collection/src/query.ts)preload() fix (
packages/db/src/collection/sync.ts)status:errorevents and reject the promiseCollection lifecycle improvements (
packages/db/src/collection/)markError()method for sync implementations to set error stateeventsproperty public (was_eventsprivate)markReady()now auto-handles error recovery by transitioning through loading state (error → loading → ready)errorcan transition toidleorloadingTest plan
@tanstack/electric-db-collection@tanstack/query-db-collectionpreload()rejects after 10 seconds of errors🤖 Generated with Claude Code