What causes "no searchPagePath provided in themeConfig.algolia" in facebook/docusaurus?

Set searchPagePath to a real path (e.g. 'search', the default) if you want OpenSearch.

no searchPagePath provided in themeConfig.algolia

Error message

no searchPagePath provided in themeConfig.algolia

What it means

Thrown by createOpenSearchFile in theme-search-algolia when themeConfig.algolia.searchPagePath is falsy while building the OpenSearch description file (opensearch.xml). searchPagePath determines the search URL embedded in the OpenSearch descriptor; without it the file cannot be generated. Note the Joi schema allows null/false to disable search, so this guard fires only when OpenSearch generation is actually attempted.

Source

Thrown at packages/docusaurus-theme-search-algolia/src/opensearch.ts:87

    searchUrl: normalizeUrl([siteUrl, searchPagePath]),
    faviconUrl: favicon ? normalizeUrl([siteUrl, favicon]) : null,
  });
}

export async function createOpenSearchFile({
  context,
}: {
  context: LoadContext;
}): Promise<void> {
  const {
    outDir,
    siteConfig: {themeConfig},
  } = context;
  const {
    algolia: {searchPagePath},
  } = themeConfig as ThemeConfig;
  if (!searchPagePath) {
    throw new Error('no searchPagePath provided in themeConfig.algolia');
  }
  const fileContent = createOpenSearchFileContent({context, searchPagePath});
  try {
    await fs.writeFile(path.join(outDir, OPEN_SEARCH_FILENAME), fileContent);
  } catch (err) {
    throw new Error('Generating OpenSearch file failed.', {cause: err});
  }
}

export function createOpenSearchHeadTags({
  context,
}: {
  context: LoadContext;
}): HtmlTags {
  const {
    baseUrl,
    siteConfig: {title},
  } = context;

View on GitHub (pinned to 3f483e80e3)

Solutions

Set searchPagePath to a real path (e.g. 'search', the default) if you want OpenSearch.
If you disabled search on purpose, ensure shouldCreateOpenSearchFile gates the call (it returns false when searchPagePath is falsy or router is hash).
Avoid calling createOpenSearchFile directly without first checking searchPagePath.

Example fix

// before
themeConfig: { algolia: { ..., searchPagePath: null } }
// after
themeConfig: { algolia: { ..., searchPagePath: 'search' } }

Defensive patterns

Strategy: validation

Validate before calling

const { searchPagePath } = siteConfig.themeConfig.algolia ?? {};
if (!searchPagePath) {
  // do not call createOpenSearchFile; rely on shouldCreateOpenSearchFile
}

Type guard

const hasSearchPagePath = (cfg: any): boolean =>
  typeof cfg?.algolia?.searchPagePath === 'string' && cfg.algolia.searchPagePath.length > 0;

Prevention

Always gate createOpenSearchFile behind shouldCreateOpenSearchFile.
If disabling search, set searchPagePath:false and skip OpenSearch generation.

When it happens

Trigger: Setting themeConfig.algolia.searchPagePath to null or false (to disable the built-in search page) while createOpenSearchFile is still invoked (e.g. shouldCreateOpenSearchFile returned true, or a custom integration calls it directly).

Common situations: Disabling the standalone search page but the OpenSearch generation path still runs; misconfigured Algolia theme config; custom head-tag/postBuild hooks that call createOpenSearchFile unconditionally.

Related errors

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