Improve DuplicateKeySyncError (#1119)

KyleAMathews · claude · web-flow · commit 1b22e40c5632 · 2026-01-19T09:54:26.000-07:00
* fix: improve DuplicateKeySyncError message for distinct + custom getKey

When using `.distinct()` with a custom `getKey`, the error message now
explains that `.distinct()` deduplicates by the entire selected object,
not by the key field. This helps users understand they should either:
1. Ensure SELECT only includes fields that make up the key
2. Use .groupBy() instead of .distinct() for explicit control
3. Remove the custom getKey to use default key behavior

This addresses a production bug where users were getting confusing
duplicate key errors when combining these features.

* chore: add changeset for improved error message

* fix: remove misleading groupBy suggestion from error message

* fix: add back groupBy suggestion with min()/max() aggregates

---------

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/distinct-getkey-error-message.md b/.changeset/distinct-getkey-error-message.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+Improve DuplicateKeySyncError message when using `.distinct()` with custom `getKey`. The error now explains that `.distinct()` deduplicates by the entire selected object, and provides actionable guidance to fix the issue.
diff --git a/packages/db/src/collection/sync.ts b/packages/db/src/collection/sync.ts
@@ -150,6 +150,7 @@ export class CollectionSyncManager<
                   throw new DuplicateKeySyncError(key, this.id, {
                     hasCustomGetKey: internal?.hasCustomGetKey ?? false,
                     hasJoins: internal?.hasJoins ?? false,
+                    hasDistinct: internal?.hasDistinct ?? false,
                   })
                 }
               }
diff --git a/packages/db/src/errors.ts b/packages/db/src/errors.ts
@@ -172,12 +172,28 @@ export class DuplicateKeySyncError extends CollectionOperationError {
   constructor(
     key: string | number,
     collectionId: string,
-    options?: { hasCustomGetKey?: boolean; hasJoins?: boolean },
+    options?: {
+      hasCustomGetKey?: boolean
+      hasJoins?: boolean
+      hasDistinct?: boolean
+    },
   ) {
     const baseMessage = `Cannot insert document with key "${key}" from sync because it already exists in the collection "${collectionId}"`
 
-    // Provide enhanced guidance when custom getKey is used with joins
-    if (options?.hasCustomGetKey && options.hasJoins) {
+    // Provide enhanced guidance when custom getKey is used with distinct
+    if (options?.hasCustomGetKey && options.hasDistinct) {
+      super(
+        `${baseMessage}. ` +
+          `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.`,
+      )
+    } else if (options?.hasCustomGetKey && options.hasJoins) {
+      // Provide enhanced guidance when custom getKey is used with joins
       super(
         `${baseMessage}. ` +
           `This collection uses a custom getKey with joined queries. ` +
diff --git a/packages/db/src/query/live/collection-config-builder.ts b/packages/db/src/query/live/collection-config-builder.ts
@@ -227,6 +227,7 @@ export class CollectionConfigBuilder<
           getBuilder: () => this,
           hasCustomGetKey: !!this.config.getKey,
           hasJoins: this.hasJoins(this.query),
+          hasDistinct: !!this.query.distinct,
         },
       },
     }
diff --git a/packages/db/src/query/live/internal.ts b/packages/db/src/query/live/internal.ts
@@ -12,4 +12,5 @@ export type LiveQueryInternalUtils = {
   getBuilder: () => CollectionConfigBuilder<any, any>
   hasCustomGetKey: boolean
   hasJoins: boolean
+  hasDistinct: boolean
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/db': patch
 +---
++
 +Improve DuplicateKeySyncError message when using `.distinct()` with custom `getKey`. The error now explains that `.distinct()` deduplicates by the entire selected object, and provides actionable guidance to fix the issue.
Original file line number	Diff line number	Diff line change
`@@ -150,6 +150,7 @@ export class CollectionSyncManager<`
`150`	`150`	`throw new DuplicateKeySyncError(key, this.id, {`
`151`	`151`	`hasCustomGetKey: internal?.hasCustomGetKey ?? false,`
`152`	`152`	`hasJoins: internal?.hasJoins ?? false,`
	`153`	`+ hasDistinct: internal?.hasDistinct ?? false,`
`153`	`154`	`})`
`154`	`155`	`}`
`155`	`156`	`}`
Original file line number	Diff line number	Diff line change
`@@ -227,6 +227,7 @@ export class CollectionConfigBuilder<`
`227`	`227`	`getBuilder: () => this,`
`228`	`228`	`hasCustomGetKey: !!this.config.getKey,`
`229`	`229`	`hasJoins: this.hasJoins(this.query),`
	`230`	`+ hasDistinct: !!this.query.distinct,`
`230`	`231`	`},`
`231`	`232`	`},`
`232`	`233`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,4 +12,5 @@ export type LiveQueryInternalUtils = {`
`12`	`12`	`getBuilder: () => CollectionConfigBuilder<any, any>`
`13`	`13`	`hasCustomGetKey: boolean`
`14`	`14`	`hasJoins: boolean`
	`15`	`+ hasDistinct: boolean`
`15`	`16`	`}`