facebook/docusaurus · error · Error

Docs: using "disableVersioning: true" option on a non-versio

Error message

Docs: using "disableVersioning: true" option on a non-versioned site does not make sense.

What it means

Thrown by readVersionNames(). The function reads versions.json; if the file does not exist (or is empty) AND the user has set disableVersioning:true, the configuration is contradictory - disabling versioning on a site that is not versioned has no effect - so the build fails fast with an explanatory message.

Source

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

 * `includeCurrentVersion` to be true);
 * - If `includeCurrentVersion` is turned on, "current" will be inserted at the
 * beginning, if not already there.
 *
 * You need to use {@link filterVersions} after this.
 *
 * @throws Throws an error if `disableVersioning: true` but `versions.json`
 * doesn't exist (i.e. site is not versioned)
 * @throws Throws an error if versions list is empty (empty `versions.json` or
 * `disableVersioning` is true, and not including current version)
 */
export async function readVersionNames(
  siteDir: string,
  options: PluginOptions,
): Promise<string[]> {
  const versionFileContent = await readVersionsFile(siteDir, options.id);

  if (!versionFileContent && options.disableVersioning) {
    throw new Error(
      `Docs: using "disableVersioning: true" option on a non-versioned site does not make sense.`,
    );
  }

  const versions = options.disableVersioning ? [] : (versionFileContent ?? []);

  // We add the current version at the beginning, unless:
  // - user don't want to; or
  // - it's already been explicitly added to versions.json
  if (
    options.includeCurrentVersion &&
    !versions.includes(CURRENT_VERSION_NAME)
  ) {
    versions.unshift(CURRENT_VERSION_NAME);
  }

  if (versions.length === 0) {
    throw new Error(

View on GitHub (pinned to 3f483e80e3)

Solutions

1. If you do not need versioning, simply remove `disableVersioning: true` from the docs plugin options (an unversioned site works without it).
2. If you intend to disable versioning on a previously-versioned site, keep versions.json present (or first run at least one version cut) so the option has something to disable.
3. Remove the option entirely and rely on the default (versioning off until you cut a version).

Example fix

// docusaurus.config.js - before
plugins: [['@docusaurus/plugin-content-docs', {
  disableVersioning: true, // site has no versions.json
}]]

// after: drop the option on an unversioned site
plugins: [['@docusaurus/plugin-content-docs', {}]]

// Validate the docs options combo before passing them to the plugin.
function validateDocsOptions(options, versionsJsonExists) {
  if (options.disableVersioning && !versionsJsonExists) {
    throw new Error('disableVersioning:true requires an existing versions.json; remove the option on an unversioned site.');
  }
}

function isUnversionedSite(options, versionsJsonExists) {
  return !versionsJsonExists && (options.includeCurrentVersion ?? true);
}

When it happens

Trigger: docusaurus.config.js sets docs.disableVersioning:true on a brand-new site that never ran `docusaurus docs:version` (no versions.json); disabling versioning after deleting versions.json; copying a config from a versioned site to an unversioned one without removing the flag.

Common situations: Starter templates that include `disableVersioning: true` by default; config copy-paste between projects; removing versions.json manually but leaving the option on.

Related errors

• It is not possible to use docs without any version. No versi
• The docs folder does not exist for version "${versionName}".
• Docs version "${versionMetadata.versionName}" has no docs! A
• Versions should be strings. Found type "${typeof name}" for
• Invalid version name "${name}": version name must contain at

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