fix: improve InvalidSourceError message clarity (#488)

KyleAMathews · claude · samwillis · web-flow · commit b869f68f0109 · 2025-09-03T07:00:09.000-06:00
Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
Co-authored-by: Sam Willis &lt;sam.willis@gmail.com&gt;
diff --git a/.changeset/eleven-results-smoke.md b/.changeset/eleven-results-smoke.md
@@ -0,0 +1,13 @@
+---
+"@tanstack/db": patch
+---
+
+fix: improve InvalidSourceError message clarity
+
+The InvalidSourceError now provides a clear, actionable error message that:
+
+- Explicitly states the problem is passing a non-Collection/non-subquery to a live query
+- Includes the alias name to help identify which source is problematic
+- Provides guidance on what should be passed instead (Collection instances or QueryBuilder subqueries)
+
+This replaces the generic "Invalid source" message with helpful debugging information.
diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts
@@ -302,8 +302,10 @@ export class SubQueryMustHaveFromClauseError extends QueryBuilderError {
 }
 
 export class InvalidSourceError extends QueryBuilderError {
-  constructor() {
-    super(`Invalid source`)
+  constructor(alias: string) {
+    super(
+      `Invalid source for live query: The value provided for alias "${alias}" 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.`
+    )
   }
 }
 
diff --git a/packages/db/src/query/builder/index.ts b/packages/db/src/query/builder/index.ts
@@ -70,7 +70,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
       }
       ref = new QueryRef(subQuery, alias)
     } else {
-      throw new InvalidSourceError()
+      throw new InvalidSourceError(alias)
     }
 
     return [alias, ref]

Original file line number	Diff line number	Diff line change
`@@ -302,8 +302,10 @@ export class SubQueryMustHaveFromClauseError extends QueryBuilderError {`
`302`	`302`	`}`
`303`	`303`
`304`	`304`	`export class InvalidSourceError extends QueryBuilderError {`
`305`		`- constructor() {`
`306`		- super(`Invalid source`)
	`305`	`+ constructor(alias: string) {`
	`306`	`+ super(`
	`307`	+ `Invalid source for live query: The value provided for alias "${alias}" 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.`
	`308`	`+ )`
`307`	`309`	`}`
`308`	`310`	`}`
`309`	`311`
Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {`
`70`	`70`	`}`
`71`	`71`	`ref = new QueryRef(subQuery, alias)`
`72`	`72`	`} else {`
`73`		`- throw new InvalidSourceError()`
	`73`	`+ throw new InvalidSourceError(alias)`
`74`	`74`	`}`
`75`	`75`
`76`	`76`	`return [alias, ref]`