Skip to content

An AI-powered search engine with a generative UI

fix(search): fall back after recoverable provider failures (#989)

Sushant Tiwari50ae26bfda2e
diff --git a/lib/tools/__tests__/search-fallback.test.ts b/lib/tools/__tests__/search-fallback.test.ts
new file mode 100644
index 00000000..31332b92
--- /dev/null
+++ b/lib/tools/__tests__/search-fallback.test.ts
@@ -0,0 +1,174 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+ braveSearch: vi.fn(),
+ createSearchProvider: vi.fn(),
+ tavilySearch: vi.fn()
+}))
+
+vi.mock('@/lib/tools/search/providers', () => ({
+ createSearchProvider: mocks.createSearchProvider,
+ DEFAULT_PROVIDER: 'tavily'
+}))
+
+import { createSearchTool } from '@/lib/tools/search'
+
+const fallbackResult = {
+ results: [
+ {
+ title: 'Fallback result',
+ content: 'Fallback content',
+ url: 'https://example.com/result'
+ }
+ ],
+ images: [],
+ query: 'current events',
+ number_of_results: 1
+}
+
+function executeGeneralSearch(searchDepth = 'basic') {
+ const result = createSearchTool('openai:gpt-4o-mini').execute?.(
+ {
+ query: 'current events',
+ type: 'general',
+ content_types: ['web'],
+ max_results: 10,
+ search_depth: searchDepth,
+ include_domains: [],
+ exclude_domains: []
+ },
+ { toolCallId: 'search-call', messages: [], context: {} }
+ )
+
+ return (result as AsyncIterable<unknown>)[Symbol.asyncIterator]()
+}
+
+describe('general search provider fallback', () => {
+ beforeEach(() => {
+ vi.stubEnv('BRAVE_SEARCH_API_KEY', 'test-key')
+ vi.stubEnv('SEARCH_API', 'tavily')
+ mocks.createSearchProvider.mockImplementation(provider => ({
+ search: provider === 'brave' ? mocks.braveSearch : mocks.tavilySearch
+ }))
+ mocks.tavilySearch.mockResolvedValue(fallbackResult)
+ vi.spyOn(console, 'log').mockImplementation(() => undefined)
+ vi.spyOn(console, 'error').mockImplementation(() => undefined)
+ })
+
+ afterEach(() => {
+ vi.unstubAllEnvs()
+ vi.restoreAllMocks()
+ vi.clearAllMocks()
+ })
+
+ it('uses the optimized provider after the general provider is rate limited', async () => {
+ mocks.braveSearch.mockRejectedValue(
+ Object.assign(new Error('Brave search failed: HTTP 429'), { status: 429 })
+ )
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const iterator = executeGeneralSearch()
+
+ await iterator.next()
+ const complete = await iterator.next()
+
+ expect(complete.value).toMatchObject({
+ state: 'complete',
+ results: fallbackResult.results,
+ toolCallId: 'search-call',
+ provider: 'tavily',
+ fallback: {
+ from: 'brave',
+ to: 'tavily',
+ reason: { type: 'http', status: 429 }
+ }
+ })
+ expect(mocks.braveSearch).toHaveBeenCalledOnce()
+ expect(mocks.tavilySearch).toHaveBeenCalledOnce()
+ expect(warn).toHaveBeenCalledWith(
+ '[Search] dedicated general search provider brave failed with HTTP 429; using optimized search provider: tavily'
+ )
+ })
+
+ it('uses the optimized provider after a transport failure', async () => {
+ mocks.braveSearch.mockRejectedValue(new TypeError('fetch failed'))
+ vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const iterator = executeGeneralSearch()
+
+ await iterator.next()
+ const complete = await iterator.next()
+
+ expect(mocks.tavilySearch).toHaveBeenCalledOnce()
+ expect(complete.value).toMatchObject({
+ provider: 'tavily',
+ fallback: {
+ from: 'brave',
+ to: 'tavily',
+ reason: { type: 'transport' }
+ }
+ })
+ })
+
+ it('logs a recoverable HTTP status found on a nested cause', async () => {
+ const cause = Object.assign(new Error('upstream unavailable'), {
+ status: 503
+ })
+ mocks.braveSearch.mockRejectedValue(new Error('search failed', { cause }))
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+ const iterator = executeGeneralSearch()
+
+ await iterator.next()
+ await iterator.next()
+
+ expect(warn).toHaveBeenCalledWith(
+ '[Search] dedicated general search provider brave failed with HTTP 503; using optimized search provider: tavily'
+ )
+ })
+
+ it('normalizes an empty search depth to basic', async () => {
+ mocks.braveSearch.mockResolvedValue(fallbackResult)
+ const iterator = executeGeneralSearch('')
+
+ await iterator.next()
+ await iterator.next()
+
+ expect(mocks.braveSearch).toHaveBeenCalledWith(
+ 'current events',
+ 10,
+ 'basic',
+ [],
+ [],
+ expect.any(Object)
+ )
+ })
+
+ it('does not fall back for a client error', async () => {
+ mocks.braveSearch.mockRejectedValue(
+ Object.assign(new Error('Brave search failed: HTTP 400'), { status: 400 })
+ )
+ const iterator = executeGeneralSearch()
+
+ await iterator.next()
+
+ await expect(iterator.next()).rejects.toMatchObject({
+ name: 'ToolFailureError',
+ status: 400
+ })
+ expect(mocks.tavilySearch).not.toHaveBeenCalled()
+ })
+
+ it('does not retry the same provider as a fallback', async () => {
+ vi.stubEnv('SEARCH_API', 'brave')
+ mocks.braveSearch.mockRejectedValue(
+ Object.assign(new Error('Brave search failed: HTTP 429'), { status: 429 })
+ )
+ const iterator = executeGeneralSearch()
+
+ await iterator.next()
+
+ await expect(iterator.next()).rejects.toMatchObject({
+ name: 'ToolFailureError',
+ status: 429
+ })
+ expect(mocks.braveSearch).toHaveBeenCalledOnce()
+ })
+})
diff --git a/lib/tools/__tests__/search-to-model-output.test.ts b/lib/tools/__tests__/search-to-model-output.test.ts
index d6f02d67..06ed07c1 100644
--- a/lib/tools/__tests__/search-to-model-output.test.ts
+++ b/lib/tools/__tests__/search-to-model-output.test.ts
@@ -23,7 +23,13 @@ describe('search tool toModelOutput', () => {
1: { title: 'A', url: 'https://a.test', content: 'alpha' },
2: { title: 'B', url: 'https://b.test', content: 'beta' }
},
- toolCallId: 'call_123'
+ toolCallId: 'call_123',
+ provider: 'tavily',
+ fallback: {
+ from: 'brave',
+ to: 'tavily',
+ reason: { type: 'http', status: 429 }
+ }
}
const getModelValue = async (output: unknown) => {
@@ -44,6 +50,13 @@ describe('search tool toModelOutput', () => {
expect(value).not.toHaveProperty('state')
})
+ it('keeps trace metadata out of the model output', async () => {
+ const value = await getModelValue(fullOutput)
+
+ expect(value).not.toHaveProperty('provider')
+ expect(value).not.toHaveProperty('fallback')
+ })
+
it('preserves the fields the model needs to answer and to cite', async () => {
const value = await getModelValue(fullOutput)
@@ -69,6 +82,8 @@ describe('search tool toModelOutput', () => {
expect(fullOutput).toHaveProperty('citationMap')
expect(fullOutput).toHaveProperty('state')
+ expect(fullOutput).toHaveProperty('provider')
+ expect(fullOutput).toHaveProperty('fallback')
})
it('handles non-object output defensively', async () => {
diff --git a/lib/tools/search.ts b/lib/tools/search.ts
index e3098727..f5196b75 100644
--- a/lib/tools/search.ts
+++ b/lib/tools/search.ts
@@ -15,6 +15,30 @@ import {
DEFAULT_PROVIDER,
SearchProviderType
} from './search/providers'
+import {
+ classifyRecoverableSearchError,
+ RecoverableSearchFailure
+} from './search/providers/recoverable-error'
+
+function getOptimizedSearchProviderType(): SearchProviderType {
+ return (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER
+}
+
+function getEffectiveSearchDepth(
+ provider: SearchProviderType,
+ requestedDepth: 'basic' | 'advanced'
+): 'basic' | 'advanced' {
+ return provider === 'searxng' &&
+ process.env.SEARXNG_DEFAULT_DEPTH === 'advanced'
+ ? 'advanced'
+ : requestedDepth || 'basic'
+}
+
+function describeRecoverableSearchFailure(
+ failure: RecoverableSearchFailure
+): string {
+ return failure.type === 'http' ? `HTTP ${failure.status}` : 'transport error'
+}
/**
* Creates a search tool with the appropriate schema for the given model.
@@ -51,41 +75,52 @@ export function createSearchTool(fullModel: string) {
// Use the original query as is - any provider-specific handling will be done in the provider
const filledQuery = query
let searchResult: SearchResults
+ let servedBySearchAPI: SearchProviderType
+ let fallback:
+ | {
+ from: SearchProviderType
+ to: SearchProviderType
+ reason: RecoverableSearchFailure
+ }
+ | undefined
+
+ const optimizedSearchAPI = getOptimizedSearchProviderType()
// Determine which provider to use based on type
+ let generalSearchAPI: SearchProviderType | null = null
let searchAPI: SearchProviderType
if (type === 'general') {
// Try to use dedicated general search provider
const generalProvider = getGeneralSearchProviderType()
if (generalProvider) {
+ generalSearchAPI = generalProvider
searchAPI = generalProvider
} else {
// Fallback to primary provider (optimized search provider)
- searchAPI =
- (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER
+ searchAPI = optimizedSearchAPI
console.log(
`[Search] type="general" requested but no dedicated provider available, using optimized search provider: ${searchAPI}`
)
}
} else {
// For 'optimized', use the configured provider
- searchAPI =
- (process.env.SEARCH_API as SearchProviderType) || DEFAULT_PROVIDER
+ searchAPI = optimizedSearchAPI
}
- const effectiveSearchDepthForAPI =
- searchAPI === 'searxng' &&
- process.env.SEARXNG_DEFAULT_DEPTH === 'advanced'
- ? 'advanced'
- : effectiveSearchDepth || 'basic'
+ const searchWithProvider = async (
+ provider: SearchProviderType
+ ): Promise<SearchResults> => {
+ const effectiveSearchDepthForAPI = getEffectiveSearchDepth(
+ provider,
+ effectiveSearchDepth
+ )
- console.log(
- `Using search API: ${searchAPI}, Type: ${type}, Search Depth: ${effectiveSearchDepthForAPI}`
- )
+ console.log(
+ `Using search API: ${provider}, Type: ${type}, Search Depth: ${effectiveSearchDepthForAPI}`
+ )
- try {
if (
- searchAPI === 'searxng' &&
+ provider === 'searxng' &&
effectiveSearchDepthForAPI === 'advanced'
) {
// Get the base URL using the centralized utility function
@@ -107,40 +142,69 @@ export function createSearchTool(fullModel: string) {
`Advanced search API error: ${response.status} ${response.statusText}`
)
}
- searchResult = await response.json()
- } else {
- // Use the provider factory to get the appropriate search provider
- const searchProvider = createSearchProvider(searchAPI)
-
- // Pass content_types only for Brave provider
- if (searchAPI === 'brave') {
- searchResult = await searchProvider.search(
- filledQuery,
- effectiveMaxResults,
- effectiveSearchDepthForAPI,
- include_domains,
- exclude_domains,
- {
- type: type as 'general' | 'optimized',
- content_types: content_types as Array<
- 'web' | 'video' | 'image' | 'news'
- >
- }
- )
- } else {
- searchResult = await searchProvider.search(
- filledQuery,
- effectiveMaxResults,
- effectiveSearchDepthForAPI,
- include_domains,
- exclude_domains
- )
- }
+ return response.json()
}
+
+ // Use the provider factory to get the appropriate search provider
+ const searchProvider = createSearchProvider(provider)
+
+ // Pass content_types only for Brave provider
+ if (provider === 'brave') {
+ return searchProvider.search(
+ filledQuery,
+ effectiveMaxResults,
+ effectiveSearchDepthForAPI,
+ include_domains,
+ exclude_domains,
+ {
+ type: type as 'general' | 'optimized',
+ content_types: content_types as Array<
+ 'web' | 'video' | 'image' | 'news'
+ >
+ }
+ )
+ }
+
+ return searchProvider.search(
+ filledQuery,
+ effectiveMaxResults,
+ effectiveSearchDepthForAPI,
+ include_domains,
+ exclude_domains
+ )
+ }
+
+ try {
+ searchResult = await searchWithProvider(searchAPI)
+ servedBySearchAPI = searchAPI
} catch (error) {
- console.error('Search API error:', error)
- // Re-throw the error to let AI SDK handle it properly
- throw new ToolFailureError('search', error)
+ const recoverableFailure = classifyRecoverableSearchError(error)
+ if (
+ generalSearchAPI !== null &&
+ generalSearchAPI !== optimizedSearchAPI &&
+ recoverableFailure !== null
+ ) {
+ console.warn(
+ `[Search] dedicated general search provider ${generalSearchAPI} failed with ${describeRecoverableSearchFailure(recoverableFailure)}; using optimized search provider: ${optimizedSearchAPI}`
+ )
+
+ try {
+ searchResult = await searchWithProvider(optimizedSearchAPI)
+ servedBySearchAPI = optimizedSearchAPI
+ fallback = {
+ from: generalSearchAPI,
+ to: optimizedSearchAPI,
+ reason: recoverableFailure
+ }
+ } catch (fallbackError) {
+ console.error('Search fallback API error:', fallbackError)
+ throw new ToolFailureError('search', fallbackError)
+ }
+ } else {
+ console.error('Search API error:', error)
+ // Re-throw the error to let AI SDK handle it properly
+ throw new ToolFailureError('search', error)
+ }
}
// No citationMap is attached: it fully duplicated `results`
@@ -163,15 +227,17 @@ export function createSearchTool(fullModel: string) {
// Yield final results with complete state
yield {
state: 'complete' as const,
- ...searchResult
+ ...searchResult,
+ provider: servedBySearchAPI,
+ ...(fallback ? { fallback } : {})
}
},
// Trim the model-facing tool result: citationMap fully duplicates
- // `results` (dropped defensively for older persisted output) and state is
- // a streaming marker. images MUST stay — getImageSpecPrompt instructs the
- // model to embed URLs verbatim from this array. toolCallId MUST stay: the
- // prompt cites as [number](#toolCallId), so the model reads the id from
- // here.
+ // `results` (dropped defensively for older persisted output), state is a
+ // streaming marker, and provider/fallback are trace diagnostics. images
+ // MUST stay — getImageSpecPrompt instructs the model to embed URLs verbatim
+ // from this array. toolCallId MUST stay: the prompt cites as
+ // [number](#toolCallId), so the model reads the id from here.
toModelOutput: ({ output }) => {
if (!output || typeof output !== 'object') {
return { type: 'json', value: (output ?? null) as JSONValue }
@@ -181,6 +247,8 @@ export function createSearchTool(fullModel: string) {
}
delete modelView.citationMap
delete modelView.state
+ delete modelView.provider
+ delete modelView.fallback
return { type: 'json', value: modelView as JSONValue }
}
})
diff --git a/lib/tools/search/providers/__tests__/recoverable-error.test.ts b/lib/tools/search/providers/__tests__/recoverable-error.test.ts
new file mode 100644
index 00000000..cd0c3369
--- /dev/null
+++ b/lib/tools/search/providers/__tests__/recoverable-error.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { classifyRecoverableSearchError } from '../recoverable-error'
+
+describe('classifyRecoverableSearchError', () => {
+ it.each([408, 429, 500, 503])(
+ 'accepts recoverable HTTP status %i',
+ status => {
+ expect(
+ classifyRecoverableSearchError(
+ Object.assign(new Error('failed'), { status })
+ )
+ ).toEqual({ type: 'http', status })
+ }
+ )
+
+ it.each([400, 401, 403, 404, 422])(
+ 'rejects client HTTP status %i',
+ status => {
+ expect(
+ classifyRecoverableSearchError(
+ Object.assign(new Error('failed'), { status })
+ )
+ ).toBeNull()
+ }
+ )
+
+ it('classifies a network failure through its cause', () => {
+ const cause = Object.assign(new Error('connection reset'), {
+ code: 'ECONNRESET'
+ })
+
+ expect(
+ classifyRecoverableSearchError(new TypeError('fetch failed', { cause }))
+ ).toEqual({ type: 'transport' })
+ })
+
+ it('preserves an HTTP status found on a nested cause', () => {
+ const cause = Object.assign(new Error('upstream unavailable'), {
+ status: 503
+ })
+
+ expect(
+ classifyRecoverableSearchError(new Error('failed', { cause }))
+ ).toEqual({ type: 'http', status: 503 })
+ })
+
+ it('does not treat an arbitrary provider exception as recoverable', () => {
+ expect(
+ classifyRecoverableSearchError(new Error('Invalid query options'))
+ ).toBeNull()
+ })
+})
diff --git a/lib/tools/search/providers/recoverable-error.ts b/lib/tools/search/providers/recoverable-error.ts
new file mode 100644
index 00000000..6471d5b5
--- /dev/null
+++ b/lib/tools/search/providers/recoverable-error.ts
@@ -0,0 +1,101 @@
+const RECOVERABLE_NETWORK_CODES = new Set([
+ 'EAI_AGAIN',
+ 'ECONNREFUSED',
+ 'ECONNRESET',
+ 'EHOSTUNREACH',
+ 'ENETUNREACH',
+ 'ENOTFOUND',
+ 'ETIMEDOUT',
+ 'UND_ERR_CONNECT_TIMEOUT',
+ 'UND_ERR_HEADERS_TIMEOUT',
+ 'UND_ERR_SOCKET'
+])
+
+function getNumericProperty(
+ error: unknown,
+ property: 'status' | 'statusCode'
+): number | undefined {
+ if (typeof error !== 'object' || error === null) return undefined
+
+ const value = (error as Record<string, unknown>)[property]
+ return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function getStringProperty(
+ error: unknown,
+ property: 'code' | 'message' | 'name'
+): string | undefined {
+ if (typeof error !== 'object' || error === null) return undefined
+
+ const value = (error as Record<string, unknown>)[property]
+ return typeof value === 'string' ? value : undefined
+}
+
+function getCause(error: unknown): unknown {
+ if (typeof error !== 'object' || error === null) return undefined
+ return (error as { cause?: unknown }).cause
+}
+
+export type RecoverableSearchFailure =
+ | { type: 'http'; status: number }
+ | { type: 'transport' }
+
+function getErrorChain(error: unknown): unknown[] {
+ const chain: unknown[] = []
+ const visited = new Set<unknown>()
+ let current = error
+
+ while (current !== undefined && !visited.has(current)) {
+ visited.add(current)
+ chain.push(current)
+ current = getCause(current)
+ }
+
+ return chain
+}
+
+/**
+ * General search can safely retry another provider only when the failure is
+ * upstream and temporary. Client errors remain terminal because another
+ * provider should not be used to reinterpret a malformed request.
+ */
+export function classifyRecoverableSearchError(
+ error: unknown
+): RecoverableSearchFailure | null {
+ const errorChain = getErrorChain(error)
+
+ // Prefer a numeric HTTP status anywhere in the cause chain. This keeps the
+ // fallback decision and its trace metadata based on the same signal.
+ for (const current of errorChain) {
+ const status =
+ getNumericProperty(current, 'status') ??
+ getNumericProperty(current, 'statusCode')
+ if (status !== undefined) {
+ return status === 408 || status === 429 || (status >= 500 && status < 600)
+ ? { type: 'http', status }
+ : null
+ }
+ }
+
+ for (const current of errorChain) {
+ const code = getStringProperty(current, 'code')
+ if (code && RECOVERABLE_NETWORK_CODES.has(code)) {
+ return { type: 'transport' }
+ }
+
+ const name = getStringProperty(current, 'name')
+ if (name === 'TimeoutError') return { type: 'transport' }
+
+ const message = getStringProperty(current, 'message')
+ if (
+ message &&
+ /failed to fetch|fetch failed|network (?:error|request failed)|timed? out/i.test(
+ message
+ )
+ ) {
+ return { type: 'transport' }
+ }
+ }
+
+ return null
+}