fix(ai): warn on unknown chat options

Author: mikemikimike

.changeset/fix-unknown-chat-options.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': patch
+---
+
+Warn when `chat()` receives unknown top-level options instead of silently dropping them.

packages/ai/src/activities/chat/index.ts

@@ -502,6 +502,51 @@ export interface TextActivityOptions<
   debug?: DebugOption
 }
 
+const CHAT_OPTION_KEYS = new Set([
+  'adapter',
+  'messages',
+  'systemPrompts',
+  'tools',
+  'mcp',
+  'metadata',
+  'modelOptions',
+  'abortController',
+  'agentLoopStrategy',
+  'lazyToolsConfig',
+  'conversationId',
+  'threadId',
+  'runId',
+  'parentRunId',
+  'state',
+  'resume',
+  'outputSchema',
+  'stream',
+  'middleware',
+  'context',
+  'debug',
+])
+
+function warnOnUnknownChatOptions(
+  options: Pick<
+    TextActivityOptions<AnyTextAdapter, SchemaInput, boolean>,
+    'debug'
+  > &
+    object,
+): void {
+  const unknownKeys = Object.keys(options).filter(
+    (key) => !CHAT_OPTION_KEYS.has(key),
+  )
+  if (unknownKeys.length === 0) return
+
+  const hint = unknownKeys.includes('providerOptions')
+    ? ' Did you mean `modelOptions`?'
+    : ''
+  resolveDebugOption(options.debug).warn(
+    `chat() received unknown top-level option(s): ${unknownKeys.join(', ')}.${hint}`,
+    { unknownKeys },
+  )
+}
+
 // ===========================
 // Chat Options Helper
 // ===========================
@@ -3642,6 +3687,7 @@ export function chat<
     TMiddleware
   >,
 ): TextActivityResult<TSchema, TStream, TTools> {
+  warnOnUnknownChatOptions(options)
   validateCapabilities(options.middleware ?? [], options.adapter)
 
   const { outputSchema, stream } = options

packages/ai/tests/debug-logging-chat.test.ts

@@ -172,6 +172,46 @@ describe('debug logging — chat integration', () => {
     expect(logger.warn).not.toHaveBeenCalled()
   })
 
+  it('warns when an unknown top-level option is spread into chat()', async () => {
+    const logger = makeSpyLogger()
+    const { adapter } = createMockAdapter({
+      iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+    })
+
+    const misplacedOptions = {
+      providerOptions: { thinking: { type: 'enabled' } },
+    }
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hello' }],
+      ...misplacedOptions,
+      debug: { logger: logger as unknown as Logger },
+    })
+    await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+    expect(logger.warn).toHaveBeenCalledTimes(1)
+    const warning = logPrefixes(logger.warn.mock.calls)[0]!
+    expect(warning).toContain('providerOptions')
+    expect(warning).toContain('modelOptions')
+  })
+
+  it('silences unknown-option warnings when the errors category is disabled', async () => {
+    const logger = makeSpyLogger()
+    const { adapter } = createMockAdapter({
+      iterations: [[ev.runStarted(), ev.runFinished('stop')]],
+    })
+
+    const stream = chat({
+      adapter,
+      messages: [{ role: 'user', content: 'hello' }],
+      ...{ providerOptions: { thinking: { type: 'enabled' } } },
+      debug: { logger: logger as unknown as Logger, errors: false },
+    })
+    await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+    expect(logger.warn).not.toHaveBeenCalled()
+  })
+
   it('omitted debug — errors still log via default ConsoleLogger', async () => {
     const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
     const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})

testing/e2e/src/routeTree.gen.ts

@@ -28,6 +28,7 @@ import { Route as ChatClientDefaultBridgeRouteImport } from './routes/chat-clien
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as ProviderIndexRouteImport } from './routes/$provider/index'
 import { Route as ApiVideoRouteImport } from './routes/api.video'
+import { Route as ApiUnknownChatOptionsRouteImport } from './routes/api.unknown-chat-options'
 import { Route as ApiTtsRouteImport } from './routes/api.tts'
 import { Route as ApiTranscriptionRouteImport } from './routes/api.transcription'
 import { Route as ApiToolsTestRouteImport } from './routes/api.tools-test'
@@ -174,6 +175,11 @@ const ApiVideoRoute = ApiVideoRouteImport.update({
   path: '/api/video',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiUnknownChatOptionsRoute = ApiUnknownChatOptionsRouteImport.update({
+  id: '/api/unknown-chat-options',
+  path: '/api/unknown-chat-options',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiTtsRoute = ApiTtsRouteImport.update({
   id: '/api/tts',
   path: '/api/tts',
@@ -484,6 +490,7 @@ export interface FileRoutesByFullPath {
   '/api/tools-test': typeof ApiToolsTestRoute
   '/api/transcription': typeof ApiTranscriptionRouteWithChildren
   '/api/tts': typeof ApiTtsRouteWithChildren
+  '/api/unknown-chat-options': typeof ApiUnknownChatOptionsRoute
   '/api/video': typeof ApiVideoRouteWithChildren
   '/$provider/': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
@@ -553,6 +560,7 @@ export interface FileRoutesByTo {
   '/api/tools-test': typeof ApiToolsTestRoute
   '/api/transcription': typeof ApiTranscriptionRouteWithChildren
   '/api/tts': typeof ApiTtsRouteWithChildren
+  '/api/unknown-chat-options': typeof ApiUnknownChatOptionsRoute
   '/api/video': typeof ApiVideoRouteWithChildren
   '/$provider': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
@@ -623,6 +631,7 @@ export interface FileRoutesById {
   '/api/tools-test': typeof ApiToolsTestRoute
   '/api/transcription': typeof ApiTranscriptionRouteWithChildren
   '/api/tts': typeof ApiTtsRouteWithChildren
+  '/api/unknown-chat-options': typeof ApiUnknownChatOptionsRoute
   '/api/video': typeof ApiVideoRouteWithChildren
   '/$provider/': typeof ProviderIndexRoute
   '/api/audio/stream': typeof ApiAudioStreamRoute
@@ -694,6 +703,7 @@ export interface FileRouteTypes {
     | '/api/tools-test'
     | '/api/transcription'
     | '/api/tts'
+    | '/api/unknown-chat-options'
     | '/api/video'
     | '/$provider/'
     | '/api/audio/stream'
@@ -763,6 +773,7 @@ export interface FileRouteTypes {
     | '/api/tools-test'
     | '/api/transcription'
     | '/api/tts'
+    | '/api/unknown-chat-options'
     | '/api/video'
     | '/$provider'
     | '/api/audio/stream'
@@ -832,6 +843,7 @@ export interface FileRouteTypes {
     | '/api/tools-test'
     | '/api/transcription'
     | '/api/tts'
+    | '/api/unknown-chat-options'
     | '/api/video'
     | '/$provider/'
     | '/api/audio/stream'
@@ -902,6 +914,7 @@ export interface RootRouteChildren {
   ApiToolsTestRoute: typeof ApiToolsTestRoute
   ApiTranscriptionRoute: typeof ApiTranscriptionRouteWithChildren
   ApiTtsRoute: typeof ApiTtsRouteWithChildren
+  ApiUnknownChatOptionsRoute: typeof ApiUnknownChatOptionsRoute
   ApiVideoRoute: typeof ApiVideoRouteWithChildren
   ProviderIndexRoute: typeof ProviderIndexRoute
 }
@@ -1041,6 +1054,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiVideoRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/unknown-chat-options': {
+      id: '/api/unknown-chat-options'
+      path: '/api/unknown-chat-options'
+      fullPath: '/api/unknown-chat-options'
+      preLoaderRoute: typeof ApiUnknownChatOptionsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/tts': {
       id: '/api/tts'
       path: '/api/tts'
@@ -1499,6 +1519,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiToolsTestRoute: ApiToolsTestRoute,
   ApiTranscriptionRoute: ApiTranscriptionRouteWithChildren,
   ApiTtsRoute: ApiTtsRouteWithChildren,
+  ApiUnknownChatOptionsRoute: ApiUnknownChatOptionsRoute,
   ApiVideoRoute: ApiVideoRouteWithChildren,
   ProviderIndexRoute: ProviderIndexRoute,
 }

testing/e2e/src/routes/api.unknown-chat-options.ts

@@ -0,0 +1,69 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chat } from '@tanstack/ai'
+import type { AnyTextAdapter, Logger } from '@tanstack/ai'
+
+export const Route = createFileRoute('/api/unknown-chat-options')({
+  server: {
+    handlers: {
+      GET: async () => {
+        const warnings: Array<string> = []
+        const logger: Logger = {
+          debug: () => {},
+          info: () => {},
+          warn: (message) => warnings.push(message),
+          error: () => {},
+        }
+        const adapter = {
+          kind: 'text',
+          name: 'unknown-chat-options-test',
+          model: 'test-model',
+          '~types': {
+            providerOptions: {} as Record<string, unknown>,
+            inputModalities: ['text'],
+            messageMetadataByModality: {
+              text: undefined,
+              image: undefined,
+              audio: undefined,
+              video: undefined,
+              document: undefined,
+            },
+            toolCapabilities: [] as ReadonlyArray<string>,
+            toolCallMetadata: undefined,
+            systemPromptMetadata: undefined as never,
+          },
+          chatStream: () =>
+            (async function* () {
+              yield {
+                type: 'RUN_STARTED',
+                runId: 'run-1',
+                threadId: 'thread-1',
+                timestamp: Date.now(),
+              }
+              yield {
+                type: 'RUN_FINISHED',
+                runId: 'run-1',
+                threadId: 'thread-1',
+                finishReason: 'stop',
+                timestamp: Date.now(),
+              }
+            })(),
+          structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+        } as unknown as AnyTextAdapter
+
+        const misplacedOptions = {
+          providerOptions: { thinking: { type: 'enabled' } },
+        }
+        for await (const _chunk of chat({
+          adapter,
+          messages: [{ role: 'user', content: 'hello' }],
+          ...misplacedOptions,
+          debug: { logger },
+        })) {
+          // Drain the stream so the route exercises the complete chat path.
+        }
+
+        return Response.json({ warnings })
+      },
+    },
+  },
+})

testing/e2e/tests/unknown-chat-options.spec.ts

@@ -0,0 +1,15 @@
+import { test, expect } from './fixtures'
+
+test.describe('chat() unknown top-level options (#1073)', () => {
+  test('warns when providerOptions is silently dropped', async ({
+    request,
+  }) => {
+    const response = await request.get('/api/unknown-chat-options')
+
+    expect(response.ok()).toBe(true)
+    const body = (await response.json()) as { warnings: Array<string> }
+    expect(body.warnings).toHaveLength(1)
+    expect(body.warnings[0]).toContain('providerOptions')
+    expect(body.warnings[0]).toContain('modelOptions')
+  })
+})