facebook/docusaurus · error

Generating OpenSearch file failed.

Error message

Generating OpenSearch file failed.

What it means

Thrown by createOpenSearchFile when fs.writeFile fails while writing opensearch.xml to the build outDir. The underlying I/O error is attached via cause. This is a runtime/build failure rather than a config error; the message is generic because the real detail lives in err.cause.

Source

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

  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;
  return {
    tagName: 'link',
    attributes: {
      rel: 'search',
      type: 'application/opensearchdescription+xml',
      title,

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Inspect err.cause for the real filesystem error (EACCES, ENOSPC, ENOENT, EBUSY).
2. Ensure the build output directory exists and is writable by the build user.
3. Avoid running two builds into the same outDir simultaneously; clear the build dir (docusaurus clear) and retry.
4. Free disk space if ENOSPC.

import fs from 'fs-extra';
await fs.ensureDir(outDir);
await fs.access(path.dirname(targetFile), fs.constants.W_OK);

try {
  await createOpenSearchFile({context});
} catch (err) {
  const cause = (err as Error & {cause?: NodeJS.ErrnoException}).cause;
  if (cause?.code === 'EACCES' || cause?.code === 'ENOENT') {
    // fix permissions/ensure dir, then retry once
  } else throw err;
}

When it happens

Trigger: outDir is not writable, disk full, path too long, permission denied, outDir was deleted mid-build, or another process holds/locks the file.

Common situations: CI runners with read-only output mounts; running build as a user lacking write perms; concurrent builds writing to the same outDir; antivirus/container filesystem quirks on Windows.

Related errors

• The redirect plugin is not supposed to override existing fil
• Processing of page source file path=${relativeSource} failed
• no searchPagePath provided in themeConfig.algolia
• Directory already exists at path=${dest}!
• Copying Docusaurus template name=${source.template.name} fai

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