Add first-class error tracking to base Collection class #672
Send to my agentBackground#
Currently, error state tracking is inconsistent across collection types:
- query-db-collection: Tracks
lastErroranderrorCountin closure variables, exposing them via utility functions (collection.utils.lastError(),collection.utils.isError(),collection.utils.errorCount()) - electric-db-collection: Has no error tracking at all - errors are thrown or logged but not stored
- Base Collection: Has
status: 'error'state but no associated error information
This creates an inconsistent developer experience where error handling differs depending on which collection type you're using.
Proposal#
Make error tracking a first-class concern in the base Collection class, similar to how status is handled today.
API Changes#
Add to CollectionLifecycleManager:
public error: Error | null = null
public errorCount: number = 0
public markError(error?: Error): void {
if (error) {
this.error = error
this.errorCount++
}
this.setStatus('error')
}
Expose on Collection:
// Direct property access (like status)
collection.error // Error | null
collection.errorCount // number
// Events
collection.on('error', (event) => {
console.log('Error occurred:', event.error)
})
Benefits#
- Consistency: All collection types have the same error API
- Better DX: Access
collection.errordirectly instead ofcollection.utils.lastError() - Framework integration: React, Angular, Vue adapters can reactively bind to error state
- Debugging: Errors are preserved and inspectable, not just logged
- Retry logic:
errorCountenables exponential backoff strategies
Migration Path#
- Add error tracking to base Collection (non-breaking - new properties)
- Update
query-db-collectionto use base error tracking instead of closure variables (internal change) - Update
electric-db-collectionto pass errors tomarkError()instead of just throwing - Deprecate
collection.utils.lastError()in favor ofcollection.error(breaking in next major)
Open Questions#
- Should
markError()clear the error on successful recovery, or should we have a separateclearError()method? - Should errors emit events (
collection.on('error', ...)) in addition to status events? - What should happen to
errorCounton recovery - reset to 0 or preserve for analytics? - Should we track error history (last N errors) or just the most recent?
Related#
- #671 - Fixed error propagation where errors weren't being set on collections at all
This came out of the discussion in #671 where we realized error tracking should be baked into the core Collection rather than being add-on utilities.
This also blocks the error contract in the live-query framework bindings RFC (#1623).
Confirmed on the current PR #1724 head: a source collection can drive a live query to
status: "error"andisError: true, while the adapter-visibleerrorremainsundefined.The loss happens before any framework adapter:
CollectionLifecycleManager.setStatus("error")records only the status.status:changeevents carry no error value.LiveQuerySnapshottherefore has no source error to expose.LiveQueryWindowControllercan expose its own pagination error, but falls back toundefinedwhen its observer reports a source error.
Suggested acceptance criteria for this issue:
- Base collections retain the current error as
unknown, not onlyError, since sync sources may throw any value. - The status and error are published as one observable transition; consumers must not see
isError: truewith a stale or missing error. - Recovery defines when the retained error is cleared and publishes that change atomically too.
- Derived live-query collections preserve or wrap the originating source error instead of replacing it with only a log message.
LiveQuerySnapshotcarrieserror: unknown, and the infinite window snapshot composes it with pagination errors.- The shared adapter conformance suite induces a source failure with a sentinel value and checks that every adapter exposes that exact value.
Issue #1260 is related but narrower: it reports a query collection staying
readyrather than entering the error state. This issue remains the better place for retaining and propagating the actual error once the status is correct.KyleAMathews(GitHub profile, opens in a new tab) closed this
🎉 The fix for this issue has been released!
Fixing PRs: https://github.com/TanStack/db/pull/2168
- @tanstack/angular-db@1.0.0-rc.1
- @tanstack/db@1.0.0-rc.1
- @tanstack/db-sqlite-persistence-core@1.0.0-rc.1
- @tanstack/electric-db-collection@1.0.0-rc.1
- @tanstack/powersync-db-collection@1.0.0-rc.1
- @tanstack/preact-db@1.0.0-rc.1
- @tanstack/react-db@1.0.0-rc.1
- @tanstack/rxdb-db-collection@1.0.0-rc.1
- @tanstack/solid-db@1.0.0-rc.1
- @tanstack/svelte-db@1.0.0-rc.1
- @tanstack/trailbase-db-collection@1.0.0-rc.1
- @tanstack/vue-db@1.0.0-rc.1
Backfilled notification for published release candidates.
Sign in to join this conversation.
I like most of this, it's a great improvement, but I think the transitioning out of error state need some more thought - see comment on the PR