facebook/docusaurus · error

The askAi feature is only supported in DocSearch v4. Please

Error message

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.

What it means

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.

Source

Thrown at packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts:136

          return askAiInput;
        },
      )
      .optional()
      .messages({
        'alternatives.types':
          'askAi must be either a string (assistantId) or an object with indexName, apiKey, appId, and assistantId',
      }),
  })
    .label('themeConfig.algolia')
    .required()
    .unknown(),
});

// TODO Docusaurus v4: remove this check when we drop DocSearch v3
function ensureAskAISupported(themeConfig: ThemeConfig) {
  // enforce DocsSearch v4 requirement when AskAI is configured
  if (themeConfig.algolia.askAi && docSearchV3) {
    throw new Error(
      '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.',
    );
  }
}

export function validateThemeConfig({
  validate,
  themeConfig: themeConfigInput,
}: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig {
  const themeConfig = validate(Schema, themeConfigInput);
  ensureAskAISupported(themeConfig);
  return themeConfig;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Upgrade @docsearch/react to ^4.0.0 (pnpm add @docsearch/react@^4 or let Docusaurus resolve it), then reinstall.
2. If you cannot upgrade yet, remove the askAi key from themeConfig.algolia.
3. Run pnpm why @docsearch/react to find what resolves the v3 version and dedupe.

Example fix

// before: askAi set with DocSearch v3 installed
themeConfig: { algolia: { ..., askAi: 'asst-xxx' } }
// after option A: upgrade
//   pnpm add @docsearch/react@^4.0.0
// after option B: remove askAi
themeConfig: { algolia: { ... } }

import semver from 'semver';
const v = require('@docsearch/react/package.json').version;
if (siteConfig.themeConfig.algolia?.askAi && semver.lt(v, '4.0.0')) {
  throw new Error('askAi requires @docsearch/react ^4.0.0');
}

When it happens

Trigger: Configuring themeConfig.algolia.askAi while a v3 @docsearch/react is resolved in node_modules (transitive dependency not upgraded).

Common situations: 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.

Related errors

• no searchPagePath provided in themeConfig.algolia
• it should be a RegExp or a string, but received ${from}
• Generating OpenSearch file failed.

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/aa0b7bf48d9a9df1. Report an issue: GitHub.