# Error Codes
Production builds of TanStack DB shorten error messages to a code, the inputs
that the error can show, and a link to this page. For example:
```text
TanStack DB error 17 (key=1, collectionId="todos"): https://tanstack.com/db/latest/docs/errors#error-17
```
A console warning uses the same form with `warning` in place of `error`.
Development builds keep the full messages below. The error classes, their
`name` values, and their fields are the same in both builds. See
[Error Handling](./guides/error-handling.md) for how to catch them.
## Error 2: `DuplicateDbInstanceError`
Development builds show the full message. For example:
```text
Multiple instances of @tanstack/db detected!
This causes transaction context to be lost because each instance maintains its own transaction stack.
Common causes:
1. Different versions of @tanstack/db installed
2. Incompatible peer dependency versions in packages
3. Module resolution issues in bundler configuration
To fix:
1. Check installed versions: npm list @tanstack/db (or pnpm/yarn list)
2. Force a single version using package manager overrides:
- npm: "overrides" in package.json
- pnpm: "pnpm.overrides" in package.json
- yarn: "resolutions" in package.json
3. Clear node_modules and lockfile, then reinstall
To temporarily disable this check (not recommended):
Set environment variable: TANSTACK_DB_DISABLE_DUP_CHECK=1
See: https://tanstack.com/db/latest/docs/troubleshooting#duplicate-instances
```
## Error 3: `InvalidSyncPersistenceCapabilityError`
Development builds show the full message. For example:
```text
Invalid sync persistence capability at metadata.persistence: reason. Custom sync wrappers must forward metadata.persistence unchanged.
```
## Error 4: `CollectionRequiresConfigError`
Development builds show the full message. For example:
```text
Collection requires a config
```
## Error 5: `CollectionRequiresSyncConfigError`
Development builds show the full message. For example:
```text
Collection requires a sync config
```
## Error 6: `InvalidSchemaError`
Development builds show the full message. For example:
```text
Schema must implement the standard-schema interface
```
## Error 7: `SchemaMustBeSynchronousError`
Development builds show the full message. For example:
```text
Schema validation must be synchronous
```
## Error 8: `CollectionInErrorStateError`
Development builds show the full message. For example:
```text
Cannot perform operation on collection "collection-1" - collection is in error state. Try calling cleanup() and restarting the collection.
```
## Error 9: `InvalidCollectionStatusTransitionError`
Development builds show the full message. For example:
```text
Invalid collection status transition from "pending" to "ready" for collection "collection-1"
```
## Error 10: `CollectionIsInErrorStateError`
Development builds show the full message. For example:
```text
Collection is in error state
```
## Error 11: `NegativeActiveSubscribersError`
Development builds show the full message. For example:
```text
Active subscribers count is negative - this should never happen
```
## Error 12: `LiveQueryObserverDisposedError`
Development builds show the full message. For example:
```text
Cannot subscribe to a disposed LiveQueryObserver
```
## Error 13: `LiveQueryWindowControllerDisposedError`
Development builds show the full message. For example:
```text
Cannot subscribe to a disposed LiveQueryWindowController
```
## Error 14: `UndefinedKeyError`
Development builds show the full message. For example:
```text
An object was created without a defined key: {"name":"item"}
```
## Error 15: `InvalidKeyError`
Development builds show the full message. For example:
```text
getKey returned an invalid key type. Expected string or number, but got null: null. Item: {"name":"item"}
```
```text
getKey returned an invalid key type. Expected string or number, but got object: {"id":1}. Item: {"name":"item"}
```
## Error 16: `DuplicateKeyError`
Development builds show the full message. For example:
```text
Cannot insert document with ID "key-1" because it already exists in the collection
```
## Error 17: `DuplicateKeySyncError`
Development builds show the full message. For example:
```text
Cannot insert document with key "123" from sync because it already exists in the collection "collection-1"
```
```text
Cannot insert document with key "key-1" from sync because it already exists in the collection "collection-1". This collection uses a custom getKey with .distinct(). The .distinct() operator deduplicates by the ENTIRE selected object (standard SQL behavior), but your custom getKey extracts only a subset of fields. This causes multiple distinct rows (with different values in non-key fields) to receive the same key. To fix this, either: (1) ensure your SELECT only includes fields that uniquely identify each row, (2) use .groupBy() with min()/max() aggregates to select one value per group, or (3) remove the custom getKey to use the default key behavior.
```
```text
Cannot insert document with key "key-1" from sync because it already exists in the collection "collection-1". This collection uses a custom getKey with joined queries. Joined queries can produce multiple rows with the same key when relationships are not 1:1. Consider: (1) using a composite key in your getKey function (e.g., `${item.key1}-${item.key2}`), (2) ensuring your join produces unique rows per key, or (3) removing the custom getKey to use the default composite key behavior.
```
## Error 18: `MissingUpdateArgumentError`
Development builds show the full message. For example:
```text
The first argument to update is missing
```
## Error 19: `NoKeysPassedToUpdateError`
Development builds show the full message. For example:
```text
No keys were passed to update
```
## Error 20: `UpdateKeyNotFoundError`
Development builds show the full message. For example:
```text
The key "key-1" was passed to update but an object for this key was not found in the collection
```
## Error 21: `KeyUpdateNotAllowedError`
Development builds show the full message. For example:
```text
Updating the key of an item is not allowed. Original key: "old-key", Attempted new key: "new-key". Please delete the old item and create a new one if a key change is necessary.
```
## Error 22: `NoKeysPassedToDeleteError`
Development builds show the full message. For example:
```text
No keys were passed to delete
```
## Error 23: `DeleteKeyNotFoundError`
Development builds show the full message. For example:
```text
Collection.delete was called with key 'key-1' but there is no item in the collection with this key
```
## Error 24: `MissingInsertHandlerError`
Development builds show the full message. For example:
```text
Collection.insert called directly (not within an explicit transaction) but no 'onInsert' handler is configured.
```
## Error 25: `MissingUpdateHandlerError`
Development builds show the full message. For example:
```text
Collection.update called directly (not within an explicit transaction) but no 'onUpdate' handler is configured.
```
## Error 26: `MissingDeleteHandlerError`
Development builds show the full message. For example:
```text
Collection.delete called directly (not within an explicit transaction) but no 'onDelete' handler is configured.
```
## Error 27: `QueueCapacityExceededError`
Development builds show the full message. For example:
```text
Queue capacity exceeded; the mutation was not admitted
```
## Error 28: `QueueDisposedError`
Development builds show the full message. For example:
```text
Queue has been cleaned up; the mutation was not admitted
```
## Error 29: `ThrottleCallDroppedError`
Development builds show the full message. For example:
```text
Throttle call was dropped because trailing execution is disabled
```
## Error 30: `DebounceCallDroppedError`
Development builds show the full message. For example:
```text
Debounce call was dropped because trailing execution is disabled
```
## Error 31: `MissingMutationFunctionError`
Development builds show the full message. For example:
```text
mutationFn is required when creating a transaction
```
## Error 32: `OnMutateMustBeSynchronousError`
Development builds show the full message. For example:
```text
onMutate must be synchronous and cannot return a promise. Remove async/await or returned promises from onMutate.
```
## Error 33: `TransactionNotPendingMutateError`
Development builds show the full message. For example:
```text
You can no longer call .mutate() as the transaction is no longer pending
```
## Error 34: `TransactionAlreadyCompletedRollbackError`
Development builds show the full message. For example:
```text
You can no longer call .rollback() as the transaction is already completed
```
## Error 35: `TransactionNotPendingCommitError`
Development builds show the full message. For example:
```text
You can no longer call .commit() as the transaction is no longer pending
```
## Error 36: `NoPendingSyncTransactionWriteError`
Development builds show the full message. For example:
```text
No pending sync transaction to write to
```
## Error 37: `SyncTransactionAlreadyCommittedWriteError`
Development builds show the full message. For example:
```text
The pending sync transaction is already committed, you can't still write to it.
```
## Error 38: `SyncRowReusedWithoutPreviousValueError`
Development builds show the full message. For example:
```text
A sync update for key "key-1" wrote a row object that changed in place since it was last written. The change overwrote the row's previous value. Write a new object, or pass the row's previous value as `previousValue`.
```
## Error 39: `NoPendingSyncTransactionCommitError`
Development builds show the full message. For example:
```text
No pending sync transaction to commit
```
## Error 40: `SyncTransactionAlreadyCommittedError`
Development builds show the full message. For example:
```text
The pending sync transaction is already committed, you can't commit it again.
```
## Error 41: `SyncQueueInvariantError`
Development builds show the full message. For example:
```text
Sync queue invariant failed: invariant detail
```
## Error 42: `OnlyOneSourceAllowedError`
Development builds show the full message. For example:
```text
Only one source is allowed in the join clause
```
## Error 43: `SubQueryMustHaveFromClauseError`
Development builds show the full message. For example:
```text
A sub query passed to a join clause must have a from clause itself
```
## Error 44: `InvalidSourceError`
Development builds show the full message. For example:
```text
Invalid source for live query: The value provided for alias "todos" is not a Collection or subquery. Live queries only accept Collection instances or subqueries. Please ensure you're passing a valid Collection or QueryBuilder, not a plain array or other data type.
```
## Error 45: `InvalidSourceTypeError`
Development builds show the full message. For example:
```text
Invalid source for from clause: Expected an object with a single key-value pair like { alias: collection }. For example: .from({ todos: todosCollection }). Got: string
```
```text
Invalid source for join clause: Expected an object with a single key-value pair like { alias: collection }. For example: .join({ todos: todosCollection }, ({ todo, todos }) => eq(todo.id, todos.id)). Got: number
```
```text
Invalid source for unionAll clause: Expected an object with one or more key-value pairs like { alias: collection }. For example: .unionAll({ todos: todosCollection, events: eventsCollection }). Got: undefined
```
## Error 46: `JoinConditionMustBeEqualityError`
Development builds show the full message. For example:
```text
Join condition must be an equality expression or a nonempty conjunction of equality expressions
```
## Error 47: `QueryMustHaveFromClauseError`
Development builds show the full message. For example:
```text
Query must have a from clause
```
## Error 48: `InvalidWhereExpressionError`
Development builds show the full message. For example:
```text
Invalid where() expression: Expected a query expression, but received a boolean. This usually happens when using JavaScript's comparison operators (===, !==, <, >, etc.) directly. Instead, use the query builder functions:
❌ .where(({ user }) => user.id === 'abc')
✅ .where(({ user }) => eq(user.id, 'abc'))
Available comparison functions: eq, gt, gte, lt, lte, and, or, not, like, ilike, isNull, isUndefined
```
## Error 49: `UnsafeAliasPathError`
Development builds show the full message. For example:
```text
Unsafe alias path segment "__proto__" is not allowed in .select(). Aliases must not contain "__proto__", "prototype", or "constructor".
```
## Error 50: `DistinctRequiresSelectError`
Development builds show the full message. For example:
```text
DISTINCT requires a SELECT clause.
```
## Error 51: `FnSelectWithGroupByError`
Development builds show the full message. For example:
```text
fn.select() cannot be used with groupBy(). groupBy requires the compiler to statically analyze aggregate functions (count, sum, max, etc.) in the SELECT clause, which is not possible with fn.select() since it is an opaque function. Use .select() instead of .fn.select() when combining with groupBy().
```
## Error 52: `UnsupportedFnSelectResultError`
Development builds show the full message. For example:
```text
fn.select() cannot return query builder. Child query builders, query expressions, and helpers such as eq(), toArray(), materialize(), concat(toArray()), and caseWhen() are query-construction values. Use them as direct fields in .select() instead.
```
## Error 53: `UnsupportedRootScalarSelectError`
Development builds show the full message. For example:
```text
Top-level scalar select() is not supported by createLiveQueryCollection() or queryOnce(). Return an object from .select(), or use the scalar query inside toArray(...) or concat(toArray(...)).
```
## Error 54: `HavingRequiresGroupByError`
Development builds show the full message. For example:
```text
HAVING clause requires GROUP BY clause
```
## Error 55: `LimitOffsetRequireOrderByError`
Development builds show the full message. For example:
```text
LIMIT and OFFSET require an ORDER BY clause to ensure deterministic results
```
## Error 56: `CollectionInputNotFoundError`
Development builds show the full message. For example:
```text
Input for alias "alias" (collection "collection-1") not found in inputs map. Available keys: key1, key2
```
```text
Input for collection "alias" not found in inputs map
```
## Error 57: `DuplicateAliasInSubqueryError`
Development builds show the full message. For example:
```text
Subquery uses alias "alias" which is already used in the parent query. Each alias must be unique across parent and subquery contexts. Parent query aliases: parent1, parent2. Please rename "alias" in either the parent query or subquery to avoid conflicts.
```
## Error 58: `UnsupportedFromTypeError`
Development builds show the full message. For example:
```text
Unsupported FROM type: string
```
## Error 59: `UnknownExpressionTypeError`
Development builds show the full message. For example:
```text
Unknown expression type: custom
```
## Error 60: `EmptyReferencePathError`
Development builds show the full message. For example:
```text
Reference path cannot be empty
```
## Error 61: `UnknownFunctionError`
Development builds show the full message. For example:
```text
Unknown function: customFn
```
## Error 62: `JoinCollectionNotFoundError`
Development builds show the full message. For example:
```text
Collection "collection-1" not found during compilation of join
```
## Error 63: `UnsupportedJoinTypeError`
Development builds show the full message. For example:
```text
Unsupported join type: OUTER
```
## Error 64: `InvalidJoinConditionSameSourceError`
Development builds show the full message. For example:
```text
Invalid join condition: both expressions refer to the same source "todos"
```
## Error 65: `InvalidJoinConditionSourceMismatchError`
Development builds show the full message. For example:
```text
Invalid join condition: expressions must reference source aliases
```
## Error 66: `InvalidJoinConditionLeftSourceError`
Development builds show the full message. For example:
```text
Invalid join condition: left expression refers to an unavailable source "todos"
```
## Error 67: `InvalidJoinConditionRightSourceError`
Development builds show the full message. For example:
```text
Invalid join condition: right expression does not refer to the joined source "comments"
```
## Error 68: `InvalidJoinCondition`
Development builds show the full message. For example:
```text
Invalid join condition
```
## Error 69: `UnsupportedJoinSourceTypeError`
Development builds show the full message. For example:
```text
Unsupported join source type: custom
```
## Error 70: `NonAggregateExpressionNotInGroupByError`
Development builds show the full message. For example:
```text
Non-aggregate expression 'field' in SELECT must also appear in GROUP BY clause
```
## Error 71: `UnsupportedAggregateFunctionError`
Development builds show the full message. For example:
```text
Unsupported aggregate function: customAgg
```
## Error 72: `AggregateFunctionNotInSelectError`
Development builds show the full message. For example:
```text
Aggregate function in HAVING clause must also be in SELECT clause: count
```
## Error 73: `UnknownHavingExpressionTypeError`
Development builds show the full message. For example:
```text
Unknown expression type in HAVING clause: custom
```
## Error 74: `SerializationError`
Development builds show the full message. For example:
```text
Cannot write item because it cannot be JSON serialized: circular reference
```
## Error 75: `StorageKeyRequiredError`
Development builds show the full message. For example:
```text
[LocalStorageCollection] storageKey must be provided.
```
## Error 76: `InvalidStorageDataFormatError`
Development builds show the full message. For example:
```text
[LocalStorageCollection] Invalid data format in storage key "storageKey" for key "key".
```
## Error 77: `InvalidStorageObjectFormatError`
Development builds show the full message. For example:
```text
[LocalStorageCollection] Invalid data format in storage key "storageKey". Expected object format.
```
## Error 78: `SyncCleanupError`
Development builds show the full message. For example:
```text
Collection "collection-1" sync cleanup function threw an error: Cleanup failed
```
```text
Collection "collection-1" sync cleanup function threw an error: Cleanup threw
```
## Error 79: `SyncTransactionAbortedError`
Development builds show the full message. For example:
```text
Sync transaction was aborted before application
```
## Error 80: `CollectionPreloadAbortedError`
Development builds show the full message. For example:
```text
Collection preload was abandoned during cleanup
```
## Error 81: `LoadSubsetOperationAbortedError`
Development builds show the full message. For example:
```text
Load subset operation was aborted before its result became visible
```
## Error 82: `CannotCombineEmptyExpressionListError`
Development builds show the full message. For example:
```text
Cannot combine empty expression list
```
## Error 83: `MissingAliasInputsError`
Development builds show the full message. For example:
```text
Internal error: compiler returned aliases without inputs: alias1, alias2. This indicates a bug in query compilation. Please report this issue.
```
## Error 84: `SetWindowRequiresOrderByError`
Development builds show the full message. For example:
```text
setWindow() can only be called on collections with an ORDER BY clause. Add .orderBy() to your query to enable window movement.
```
## Error 85: `SetWindowReentrancyError`
Development builds show the full message. For example:
```text
setWindow() cannot run reentrantly. Wait for the current window operation to return before starting another one.
```
## Error 86: `PacedTransactionManualCommitError`
Development builds show the full message. For example:
```text
Paced mutations are committed by their strategy. Await the transaction receipt or roll it back instead.
```
## Error 87: `UnhashableQueryIRError`
Development builds show the full message. For example:
```text
Query IR is not stably hashable at query.fnSelect: function select
```
## Error 175: `DatabaseRequiredError`
Development builds show the full message. For example:
```text
IndexedDB collection requires a "db" configuration option. Create a database instance using createIndexedDB() and pass it to the collection.
```
## Error 176: `ObjectStoreNotFoundError`
Development builds show the full message. For example:
```text
Object store "todos" not found in database "app". Available stores: [users, posts]. Add "todos" to the stores array when calling createIndexedDB().
```
## Error 177: `NameRequiredError`
Development builds show the full message. For example:
```text
IndexedDB collection requires a "name" configuration option. This is the name of the object store within the database.
```
## Error 178: `GetKeyRequiredError`
Development builds show the full message. For example:
```text
IndexedDB collection requires a "getKey" configuration option. This function extracts the unique key from each item.
```
## Other errors and log messages
These are plain `Error`, `TypeError`, `RangeError`, or
`AggregateError` values, and `console` messages about runtime failures.
Each heading names the source file under `packages/db/src` that writes it.
## Error 88: `client.ts`
Development builds show this message, with `${...}` replaced by values:
```text
collectionOptions requires a non-empty explicit id so the descriptor is stable across DbClient instances and SSR boundaries.
```
## Error 89: `client.ts`
Development builds show this message, with `${...}` replaced by values:
```text
collectionOptions("${id}") requires a factory as its second argument.
```
## Error 90: `client.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Collection descriptor "${id}" was created from a concrete config that cannot be safely reused across DbClient instances. Use collectionOptions("${id}", (client) => adapterCollectionOptions(...)) or an adapter options creator that supports DbClient materialization.
```
## Error 91: `client.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Collection descriptor "${id}" materialized a config with id "${materialized.id}". Descriptor and collection ids must match.
```
## Error 92: `client.ts`
Development builds show this message, with `${...}` replaced by values:
```text
DbClient is missing the required "${key}" dependency. Pass it explicitly when constructing the client: new DbClient({ ${key} }).
```
## Error 93: `client.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Dehydrated live query "${dehydratedQuery.queryHash}" has neither a snapshot nor a promise.
```
## Error 94: `collection/change-events.ts`
Development builds show this message, with `${...}` replaced by values:
```text
limit cannot be used without orderBy
```
## Error 95: `collection/changes.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Cannot specify both 'where' and 'whereExpression' options. Use one or the other.
```
## Error 96: `collection/subscription.ts`
Development builds show this message, with `${...}` replaced by values:
```text
limit is required
```
## Error 97: `collection/subscription.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Ordered snapshot was requested but no index was found. You have to call setOrderByIndex before requesting an ordered snapshot.
```
## Error 98: `event-emitter.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Timeout waiting for event ${String(event)}
```
## Error 99: `indexes/base-index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to evaluate index expression for key ${key}: ${error}
```
## Error 100: `indexes/basic-index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Operation ${operation} not supported by BasicIndex
```
## Error 101: `indexes/btree-index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Operation ${operation} not supported by BTreeIndex
```
## Error 102: `live-query-options.ts`
Development builds show this message, with `${...}` replaced by values:
```text
A live query must be a QueryBuilder, LiveQueryCollectionConfig, Collection, undefined, or null. Got: ${typeof value}
```
## Error 103: `live-query-window-controller.ts`
Development builds show this message, with `${...}` replaced by values:
```text
useLiveInfiniteQuery: First argument must be either a pre-created live query collection or a query function. Received: ${typeof input}
```
## Error 104: `live-query-window-controller.ts`
Development builds show this message, with `${...}` replaced by values:
```text
useLiveInfiniteQuery: Query function must return a query builder. Disabled null or undefined queries are not supported.
```
## Error 105: `live-query-window-controller.ts`
Development builds show this message, with `${...}` replaced by values:
```text
useLiveInfiniteQuery: Infinite queries do not support single-result queries. Remove .findOne().
```
## Error 106: `live-query-window-controller.ts`
Development builds show this message, with `${...}` replaced by values:
```text
useLiveInfiniteQuery: Pre-created live query collection must have an ORDER BY (orderBy) clause for infinite pagination to work. Please add .orderBy() to your createLiveQueryCollection query.
```
## Error 107: `paced-mutations.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Strategy callback called but transaction is in state "${transaction.state}". Expected "pending".
```
## Error 108: `paced-mutations.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Paced transaction has no strategy-owned commit
```
## Error 109: `proxy.ts`
Development builds show this message, with `${...}` replaced by values:
```text
forEach callback must be a function
```
## Error 110: `query/builder/functions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
concat(toArray(...)) currently supports only a single toArray(...) argument
```
## Error 111: `query/builder/functions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
caseWhen() requires at least two arguments
```
## Error 112: `query/builder/functions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
caseWhen() conditions must be expression-like values
```
## Error 113: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Cannot use collection descriptor "${alias}" as a query source without a DbClient resolver. In React, wrap your tree in .
```
## Error 114: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Conditional include branch is missing a field name
```
## Error 115: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
toArray() must wrap a subquery builder
```
## Error 116: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Conditional toArray() branch is missing a field name
```
## Error 117: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
concat(toArray(...)) must wrap a subquery builder
```
## Error 118: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Conditional concat(toArray(...)) branch is missing a field name
```
## Error 119: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
toArray() must wrap a subquery builder
```
## Error 120: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
concat(toArray(...)) must wrap a subquery builder
```
## Error 121: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
materialize() must wrap a subquery builder
```
## Error 122: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
caseWhen() requires at least two arguments
```
## Error 123: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Includes subquery for "${fieldName}" must have a WHERE clause with an eq() condition that correlates a parent field with a child field. Example: .where(({child}) => eq(child.parentId, parent.id))
```
## Error 124: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
concat(toArray(...)) for "${fieldName}" requires the subquery to select a scalar value
```
## Error 125: `query/builder/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Includes subquery for "${fieldName}" must select an object when materializing as a Collection
```
## Error 126: `query/builder/ref-proxy.ts`
Development builds show this message, with `${...}` replaced by values:
```text
${name} cannot be used inside expressions (e.g., coalesce(), eq(), not()). Use ${name} directly as a select field value instead.
```
## Error 127: `query/compiler/evaluators.ts`
Development builds show this message, with `${...}` replaced by values:
```text
caseWhen() requires at least two arguments
```
## Error 128: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
fn.select() cannot consume Collection-valued includes. Use toArray() or materialize() in the upstream select(), or use an expression select() to keep live Collections.
```
## Error 129: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Query row has negative multiplicity
```
## Error 130: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Query row has no positive contributor
```
## Error 131: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Query contributors with the same row key are not congruent
```
## Error 132: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Duplicate source alias "${source.alias}" in unionAll query branches. Use distinct aliases in each branch before passing them to unionAll().
```
## Error 133: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Includes subqueries must be at the top level of select(). Found nested includes at "${parentPath}.${key}".
```
## Error 134: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Source collection '${collectionId}' was cleaned up while effect depends on it
```
## Error 135: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Source collection '${collectionId}' entered error state
```
## Error 136: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
No handler provided for operator: ${name}. Available handlers: ${Object.keys(handlers).join(`, `)}
```
## Error 137: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
ORDER BY expression must be a field reference, got: ${clause.expression.type}
```
## Error 138: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons requires a comparison or null check inside 'not' operator.
```
## Error 139: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons requires a field reference for '${arg.name}' operator.
```
## Error 140: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons requires simple field-value comparisons. Found complex expression for 'not(${arg.name})' operator.
```
## Error 141: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons does not support 'not(${arg.name})'. NOT can only wrap comparison operators (eq, gt, gte, lt, lte, in) or null checks (isNull, isUndefined).
```
## Error 142: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons does not support '${e.name}' operator. Use parseWhereExpression with custom handlers for complex expressions.
```
## Error 143: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons requires a field reference for '${e.name}' operator.
```
## Error 144: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons requires simple field-value comparisons. Found complex expression for '${e.name}' operator.
```
## Error 145: `query/expression-helpers.ts`
Development builds show this message, with `${...}` replaced by values:
```text
extractSimpleComparisons encountered unknown operator: '${e.name}'
```
## Error 146: `query/live/bucket-facade-adapter.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Bucket facade row has no public key
```
## Error 147: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Source recovery failed
```
## Error 148: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
maybeRunGraph called without active sync run. This should not happen.
```
## Error 149: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
scheduleGraphRun called without active sync run. This should not happen.
```
## Error 150: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Live query result key ${String(key)} changed by ${inserts - deletes} rows in one flush; a key has at most one result row.
```
## Error 151: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Could not apply changes: ${JSON.stringify(changes)}. This should never happen.
```
## Error 152: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Source collection '${collectionId}' was manually cleaned up while live query '${this.id}' depends on it. Live queries prevent automatic GC, so this was likely a manual cleanup() call.
```
## Error 153: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Query '${this.id}' has no collection sources. This should not happen; please report.
```
## Error 154: `query/live/materialized-pipeline.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Canonical query row has negative multiplicity
```
## Error 155: `query/live/materialized-pipeline.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Canonical query row has no positive contributor
```
## Error 156: `query/live/materialized-pipeline.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Query contributors for public key ${serializeValue(left.publicKey)} are not congruent
```
## Error 157: `query/live/materialized-pipeline.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Materialization bucket row has negative multiplicity
```
## Error 158: `query/live/materialized-pipeline.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Collection includes require a bucket facade
```
## Error 159: `query/live/subset-demand-controller.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Subset demand snapshot did not start
```
## Error 160: `query/live/utils.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to extract collection. Invalid FROM clause: ${JSON.stringify(query)}
```
## Error 161: `scheduler.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Scheduler detected unresolved dependencies for context ${String(contextId)}.
```
## Error 162: `transactions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
A transaction created with createTransaction() cannot mutate collections from multiple DbClient instances. Use dbClient.createTransaction() for explicit client scope.
```
## Error 163: `transactions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Transaction is not associated with a TransactionScope.
```
## Error 164: `transactions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Transaction is not associated with an ambient scope.
```
## Error 165: `transactions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Unhandled mutation combination: ${_exhaustive}
```
## Error 166: `utils/comparison.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Index comparator must return a number, but returned ${String(result)}
```
## Error 167: `utils/comparison.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Cannot order Temporal values of different types: ${aTag} vs ${bTag}
```
## Error 168: `utils/comparison.ts`
Development builds show this message, with `${...}` replaced by values:
```text
${aTag} has no defined ordering
```
## Error 169: `utils/cursor.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Only leading-column cursors are supported
```
## Error 170: `utils/error.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Unknown error
```
## Error 171: `utils/uuid.ts`
Development builds show this message, with `${...}` replaced by values:
```text
No secure random number generator available: neither crypto.randomUUID nor crypto.getRandomValues is defined in this environment.
```
## Error 172: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Source collection '${collectionId}' entered error state
```
## Error 173: `collection/lifecycle.ts`
Development builds show this message, with `${...}` replaced by values:
```text
${syncFailure ? Adapter cleanup and local teardown both failed : Multiple local teardown steps failed}
```
## Error 174: `transactions.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Mutation callback and restoration failed
```
## Error 179: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
IndexedDB is not available in this environment. Ensure you are running in a browser or provide a custom IDBFactory for testing.
```
## Error 182: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to open IndexedDB database "${name}": ${error instanceof Error ? error.message : String(error)}
```
## Error 183: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Database upgrade failed for "${name}": ${error instanceof Error ? error.message : String(error)}
```
## Error 184: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to open IndexedDB database "${name}": ${errorMessage}
```
## Error 185: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Cannot create object store "${storeName}": This operation is only allowed during a database upgrade. Ensure you are calling createObjectStore within the onUpgrade callback of openDatabase.
```
## Error 186: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Object store "${storeName}" already exists in the database. Check the database version and only create stores when needed.
```
## Error 187: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to create object store "${storeName}": ${error instanceof Error ? error.message : String(error)}
```
## Error 188: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to create transaction for stores [${storeNamesArray.join(', ')}]: ${error instanceof Error ? error.message : String(error)}
```
## Error 189: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Object store "${storeName}" not found in the database. Ensure the store was created during the database upgrade.
```
## Error 190: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Transaction was aborted
```
## Error 191: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to delete IndexedDB database "${name}": ${error instanceof Error ? error.message : String(error)}
```
## Error 192: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to delete IndexedDB database "${name}": ${errorMessage}
```
## Error 193: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
createIndexedDB requires at least one store in the stores array.
```
## Error 194: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
createIndexedDB stores array contains duplicate store names.
```
## Error 195: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
The "_versions" store is reserved for IndexedDB Collection metadata.
```
## Error 196: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
createIndexedDB stores array contains invalid store names. Each store name must be a non-empty string.
```
## Error 197: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
IndexedDB connection "${name}" closed. Recreate its Collections with a new database instance.
```
## Error 198: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
The "_versions" store is reserved for IndexedDB Collection metadata.
```
## Error 199: `indexed-db.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Duplicate imported key: ${key}
```
## Error 200: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to get all keys from object store "${objectStore.name}": ${cause}
```
## Error 201: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to write item to object store "${objectStore.name}": ${cause}
```
## Error 202: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to delete item with key "${String(key)}" from object store "${objectStore.name}": ${cause}
```
## Error 203: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to clear object store "${objectStore.name}": ${cause}
```
## Error 204: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to get all items from object store "${objectStore.name}": ${cause}
```
## Error 205: `indexed-db-wrapper.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to get item with key "${String(key)}" from object store "${objectStore.name}": ${cause}
```
## Error 206: `collection/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
autoIndex: 'eager' requires defaultIndexType to be set. Import an index type and set it:
import { BasicIndex } from '@tanstack/db'
createCollection({ defaultIndexType: BasicIndex, autoIndex: 'eager', ... })
```
## Error 207: `collection/indexes.ts`
Development builds show this message, with `${...}` replaced by values:
```text
No index type specified and no defaultIndexType set on collection. Either pass indexType in config, or set defaultIndexType on the collection:
import { BasicIndex } from '@tanstack/db'
createCollection({ defaultIndexType: BasicIndex, ... })
```
## Error 208: `collection/lifecycle.ts`
Development builds show this message, with `${...}` replaced by values:
```text
You can't directly call "setStatus('ready'). You must use markReady instead.
```
## Error 209: `collection/lifecycle.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Cannot start collection "${this.id}" during cleanup. Restart after cleanup() completes.
```
## Error 210: `collection/sync.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Collection "${this.id}" is configured with syncMode "on-demand" but the sync function did not return a loadSubset handler. Either provide a loadSubset handler or use syncMode "eager".
```
## Error 211: `query/compiler/index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Query uses alias "${alias}" more than once. Give each source in one query a distinct alias.
```
## Error 212: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Live query graph failed
```
## Warning 213: `collection/change-events.ts`
Development builds show this message, with `${...}` replaced by values:
```text
${collection.id ? `[${collection.id}] ` : ``}Error processing where clause, falling back to full scan:
```
## Error 214: `collection/cleanup-queue.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Error in CleanupQueue task:
```
## Warning 215: `indexes/auto-index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
${collection.id ? `[${collection.id}] ` : ``}Failed to create auto-index for field path "${fieldPath.join(`.`)}":
```
## Warning 216: `indexes/base-index.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Failed to evaluate index expression for key ${key} during removal:
```
## Error 218: `local-storage.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[LocalStorageCollection] Error saving data to storage key "${config.storageKey}":
```
## Warning 219: `local-storage.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[LocalStorageCollection] Error loading data from storage key "${storageKey}":
```
## Error 220: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect '${id}'] onSourceError callback threw:
```
## Error 221: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect '${id}'] ${error.message}. Disposing effect.
```
## Error 222: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect '${id}'] failed to dispose after a source error:
```
## Error 223: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect '${id}'] failed to dispose after a startup error:
```
## Error 224: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect] Error in onError handler:
```
## Error 225: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect] Original error:
```
## Error 226: `query/effect.ts`
Development builds show this message, with `${...}` replaced by values:
```text
[Effect] Unhandled error in handler:
```
## Error 228: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Subset demand '${planId}' failed: ${normalized.message}
```
## Error 229: `query/live/collection-config-builder.ts`
Development builds show this message, with `${...}` replaced by values:
```text
Initial subset load failed: ${normalized.message}
```