facebook/docusaurus · error · Error

Docs version " " has no docs! At least one doc should exist…

Error message

Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path.relative(context.siteDir, versionMetadata.contentPath)}".

What it means

Thrown by loadVersionDocsBase() at the very start of loading a version. readVersionDocs() returns the list of doc files in the version's content directory; if that list is empty the build aborts because a docs version with zero docs is meaningless. The message names the version and the relative content path where at least one doc is expected.

Solutions

1. Add at least one Markdown (.md) or MDX (.mdx) file to the directory named in the error.
2. Check options.include / options.exclude globs are not filtering out all files.
3. If the version is no longer needed, remove it from versions.json and delete its versioned_docs / versioned_sidebars folders.
4. Restore the files from version control if they were removed by mistake.

Example fix

# error: version '1.4' has no docs at versioned_docs/version-1.4/

echo '# Welcome to 1.4' > versioned_docs/version-1.4/intro.md

const fs = require('fs');
const path = require('path');
function ensureVersionHasDocs(dir) {
  const files = fs.readdirSync(dir).filter((f) => /\.mdx?$/.test(f));
  if (files.length === 0) {
    throw new Error(`No docs found in ${dir}; add at least one .md/.mdx file.`);
  }
}

function versionHasDocs(dir) {
  try {
    return fs.readdirSync(dir).some((f) => /\.mdx?$/.test(f));
  } catch { return false; }
}

When it happens

Trigger: The versioned_docs/version-<name>/ directory exists but contains no Markdown/MDX files (only non-doc files, hidden files, or an empty folder); the current docs/ directory is empty; all files in the directory match an exclude pattern; the directory contains only _category_.json with no actual docs.

Common situations: Accidentally deleting all .md files from a version; misconfigured include/exclude glob options filtering everything; empty scaffolding folder; CI step that wiped content but left the folder.

Related errors

• Invalid version name
• The docs folder does not exist for version
• 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/648090504242e849. Report an issue: GitHub.

Appendix: source

Thrown at packages/docusaurus-plugin-content-docs/src/versions/loadVersion.ts:88

    )} front matter to assign an explicit distinct id to each doc.
    `;

    throw new Error(message);
  }
}

async function loadVersionDocsBase({
  tagsFile,
  context,
  options,
  versionMetadata,
  env,
}: LoadVersionParams & {
  tagsFile: TagsFile | null;
}): Promise<DocMetadataBase[]> {
  const docFiles = await readVersionDocs(versionMetadata, options);
  if (docFiles.length === 0) {
    throw new Error(
      `Docs version "${
        versionMetadata.versionName
      }" has no docs! At least one doc should exist at "${path.relative(
        context.siteDir,
        versionMetadata.contentPath,
      )}".`,
    );
  }
  function processVersionDoc(docFile: DocFile) {
    return processDocMetadata({
      docFile,
      versionMetadata,
      context,
      options,
      env,
      tagsFile,
    });
  }

View on GitHub (pinned to 3f483e80e3)