facebook/docusaurus · error · Error

The docs folder does not exist for version

Error message

The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path.relative(context.siteDir, contentPath)}.

What it means

Thrown by getVersionMetadataPaths(). For each version, the plugin resolves a docs content directory (either siteDir/options.path for the current version, or getVersionDocsDirPath for a versioned one) and checks it with fs.pathExists. If the folder is missing the build fails, naming the version and the relative path where the folder was expected.

Solutions

1. Create the missing directory shown in the error and add at least one Markdown/MDX file to it.
2. If the version is obsolete, remove its entry from versions.json and delete its versioned_docs / versioned_sidebars folders.
3. For the current version, ensure options.path (default 'docs') resolves to an existing folder under siteDir.
4. Re-run `docusaurus docs:version <name>` to (re)generate the versioned_docs folder from current.

Example fix

# error: version '1.4' expects versioned_docs/version-1.4/

# fix: create the folder and add a doc
mkdir -p versioned_docs/version-1.4
echo '# Welcome' > versioned_docs/version-1.4/intro.md

# or remove the version if obsolete
# edit versions.json to drop '1.4', then:
rm -rf versioned_docs/version-1.4 versioned_sidebars/version-1.4-sidebars.json

const fs = require('fs');
const path = require('path');
// Ensure every version in versions.json has a docs folder.
function ensureVersionDocsFoldersExist(siteDir, pluginId, versionNames) {
  const current = path.join(siteDir, 'docs');
  if (!fs.existsSync(current)) throw new Error(`Current docs folder missing: ${current}`);
  for (const v of versionNames) {
    const dir = path.join(siteDir, 'versioned_docs', `version-${v}`);
    if (!fs.existsSync(dir)) throw new Error(`Missing docs folder for version ${v}: ${dir}`);
  }
}

function versionDocsFolderExists(siteDir, versionName) {
  const dir = versionName === 'current'
    ? path.join(siteDir, 'docs')
    : path.join(siteDir, 'versioned_docs', `version-${versionName}`);
  return fs.existsSync(dir);
}

When it happens

Trigger: A versioned_docs/version-<name>/ directory was deleted or never created; versions.json lists a version whose versioned_docs folder does not exist; options.path points at a non-existent directory for the current version; partial git checkout missing the versioned_docs subtree.

Common situations: Deleting a version's docs folder without removing it from versions.json; renaming options.path; misconfigured monorepo where the docs path is relative to the wrong siteDir; CI cache missing versioned docs.

Related errors

• Docs version " " has no docs! At least one doc should exist…
• Invalid version name
• Docs: using "disableVersioning: true" option on a…
• Invalid version name
• It is not possible to use docs without any version. No…

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

Appendix: source

Thrown at packages/docusaurus-plugin-content-docs/src/versions/files.ts:211

  const shouldTranslate = getLocaleConfig(context.i18n).translate;
  const contentPathLocalized = shouldTranslate
    ? getDocsDirPathLocalized({
        localizationDir: context.localizationDir,
        pluginId: options.id,
        versionName,
      })
    : undefined;

  const contentPath = isCurrent
    ? path.resolve(context.siteDir, options.path)
    : getVersionDocsDirPath(context.siteDir, options.id, versionName);
  const sidebarFilePath = isCurrent
    ? options.sidebarPath
    : getVersionSidebarsPath(context.siteDir, options.id, versionName);

  if (!(await fs.pathExists(contentPath))) {
    throw new Error(
      `The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path.relative(
        context.siteDir,
        contentPath,
      )}.`,
    );
  }

  // If the current version defines a path to a sidebar file that does not
  // exist, we throw! Note: for versioned sidebars, the file may not exist (as
  // we prefer to not create it rather than to create an empty file)
  // See https://github.com/facebook/docusaurus/issues/3366
  // See https://github.com/facebook/docusaurus/pull/4775
  if (
    versionName === CURRENT_VERSION_NAME &&
    typeof sidebarFilePath === 'string' &&
    !(await fs.pathExists(sidebarFilePath))
  ) {
    throw new Error(`The path to the sidebar file does not exist at "${path.relative(

View on GitHub (pinned to 3f483e80e3)