{"record":{"id":"aa0b7bf48d9a9df1","repo":"facebook/docusaurus","slug":"the-askai-feature-is-only-supported-in-docsearch-v","errorCode":null,"errorMessage":"The askAi feature is only supported in DocSearch v4. Please upgrade to DocSearch v4 by installing \"@docsearch/react\": \"^4.0.0\" or remove the askAi configuration from your theme config.","messagePattern":"The askAi feature is only supported in DocSearch v4\\. Please upgrade to DocSearch v4 by installing \"@docsearch/react\": \"\\^4\\.0\\.0\" or remove the askAi configuration from your theme config\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts","lineNumber":136,"sourceCode":"          return askAiInput;\n        },\n      )\n      .optional()\n      .messages({\n        'alternatives.types':\n          'askAi must be either a string (assistantId) or an object with indexName, apiKey, appId, and assistantId',\n      }),\n  })\n    .label('themeConfig.algolia')\n    .required()\n    .unknown(),\n});\n\n// TODO Docusaurus v4: remove this check when we drop DocSearch v3\nfunction ensureAskAISupported(themeConfig: ThemeConfig) {\n  // enforce DocsSearch v4 requirement when AskAI is configured\n  if (themeConfig.algolia.askAi && docSearchV3) {\n    throw new Error(\n      'The askAi feature is only supported in DocSearch v4. ' +\n        'Please upgrade to DocSearch v4 by installing \"@docsearch/react\": \"^4.0.0\" ' +\n        'or remove the askAi configuration from your theme config.',\n    );\n  }\n}\n\nexport function validateThemeConfig({\n  validate,\n  themeConfig: themeConfigInput,\n}: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig {\n  const themeConfig = validate(Schema, themeConfigInput);\n  ensureAskAISupported(themeConfig);\n  return themeConfig;\n}\n","sourceCodeStart":118,"sourceCodeEnd":152,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts#L118-L152","documentation":"Thrown by ensureAskAISupported in theme-search-algolia when the askAi configuration is set but the installed @docsearch/react is v3 (the docSearchV3 flag is true). The Ask AI feature requires DocSearch v4, so the guard blocks startup and tells the user to either upgrade @docsearch/react to ^4.0.0 or remove askAi. Marked for removal once DocSearch v3 support is dropped.","triggerScenarios":"Configuring themeConfig.algolia.askAi while a v3 @docsearch/react is resolved in node_modules (transitive dependency not upgraded).","commonSituations":"Adding the new Ask AI feature on a project whose lockfile still pins DocSearch 3.x; conflicting versions across the monorepo hoisting an older @docsearch/react; stale node_modules after a Docusaurus upgrade.","solutions":["Upgrade @docsearch/react to ^4.0.0 (pnpm add @docsearch/react@^4 or let Docusaurus resolve it), then reinstall.","If you cannot upgrade yet, remove the askAi key from themeConfig.algolia.","Run pnpm why @docsearch/react to find what resolves the v3 version and dedupe."],"exampleFix":"// before: askAi set with DocSearch v3 installed\nthemeConfig: { algolia: { ..., askAi: 'asst-xxx' } }\n// after option A: upgrade\n//   pnpm add @docsearch/react@^4.0.0\n// after option B: remove askAi\nthemeConfig: { algolia: { ... } }","handlingStrategy":"validation","validationCode":"import semver from 'semver';\nconst v = require('@docsearch/react/package.json').version;\nif (siteConfig.themeConfig.algolia?.askAi && semver.lt(v, '4.0.0')) {\n  throw new Error('askAi requires @docsearch/react ^4.0.0');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin @docsearch/react to ^4.0.0 when using Ask AI.","Run `pnpm why @docsearch/react` after upgrades to detect hoisted v3.","Add a CI check that asserts the DocSearch version when askAi is configured."],"tags":["algolia","search","ask-ai","docsearch","dependency-version"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}