fix(identify): reject invalid values passed to identify

packages/browser/src/__tests__/identify.test.ts

@@ -41,6 +41,50 @@ describe('identify', () => {
         )
     })
 
+    it.each([
+        ['undefined', undefined],
+        ['null', null],
+        ['empty string', ''],
+        ['false', false],
+    ])('should reject %s as a distinct_id', async (_label, invalidId) => {
+        const token = uuidv7()
+        const beforeSendMock = jest.fn().mockImplementation((e) => e)
+        const posthog = await createPosthogInstance(token, { before_send: beforeSendMock })
+
+        posthog.identify(invalidId as any)
+
+        expect(beforeSendMock).not.toHaveBeenCalled()
+        expect(mockLogger.error).toHaveBeenCalledWith('Unique user id has not been set in posthog.identify')
+    })
+
+    it('should accept the string "undefined" as a distinct_id without the 2026-04-01 defaults', async () => {
+        const token = uuidv7()
+        const beforeSendMock = jest.fn().mockImplementation((e) => e)
+        const posthog = await createPosthogInstance(token, { before_send: beforeSendMock })
+
+        posthog.identify('undefined')
+
+        expect(beforeSendMock).toHaveBeenCalled()
+        expect(mockLogger.critical).not.toHaveBeenCalled()
+    })
+
+    it('should reject the string "undefined" as a distinct_id with the 2026-04-01 defaults', async () => {
+        const token = uuidv7()
+        const beforeSendMock = jest.fn().mockImplementation((e) => e)
+        const posthog = await createPosthogInstance(token, {
+            before_send: beforeSendMock,
+            defaults: '2026-04-01',
+            internal_or_test_user_hostname: null,
+        })
+
+        posthog.identify('undefined')
+
+        expect(beforeSendMock).not.toHaveBeenCalled()
+        expect(mockLogger.critical).toHaveBeenCalledWith(
+            'The string "undefined" was set in posthog.identify which indicates an error. This ID should be unique to the user and not a hardcoded string.'
+        )
+    })
+
     it('should send $is_identified = true with the identify event and following events', async () => {
         // arrange
         const token = uuidv7()

packages/browser/src/posthog-core.ts

@@ -2350,11 +2350,17 @@
             )
             return
         }
+        if (this.config.defaults !== 'unset' && this.config.defaults >= '2026-04-01' && new_distinct_id.toLowerCase() === 'undefined') {
+            logger.critical(
+                `The string "undefined" was set in posthog.identify which indicates an error. This ID should be unique to the user and not a hardcoded string.`
+            )
+            return
+        }
 
         if (!this._requirePersonProcessing('posthog.identify')) {
             return
         }
 
         const previous_distinct_id = this.get_distinct_id()
         this.register({ $user_id: new_distinct_id })
 

packages/types/src/posthog-config.ts

@@ -284,7 +284,7 @@ export interface HeatmapConfig {
     flush_interval_milliseconds: number
 }
 
-export type ConfigDefaults = '2026-01-30' | '2025-11-30' | '2025-05-24' | 'unset'
+export type ConfigDefaults = '2026-04-01' | '2026-01-30' | '2025-11-30' | '2025-05-24' | 'unset'
 
 export type ExternalIntegrationKind = 'intercom' | 'crispChat'