facebook/docusaurus · error · Error

${pluginIdLogPrefix}: this version already exists! Use a ver

Error message

${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.

What it means

Thrown by the docs CLI version command when `docusaurus docs:version <version>` is invoked with a version name that already exists in the versions file (versions.json). The plugin refuses to overwrite a previously cut version because versioned docs/sidebars already exist for it.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/cli.ts:78

  {siteDir, i18n}: LoadContext,
): Promise<void> {
  // It wouldn't be very user-friendly to show a [default] log prefix,
  // so we use [docs] instead of [default]
  const pluginIdLogPrefix =
    pluginId === DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;

  try {
    validateVersionName(version);
  } catch (err) {
    logger.info`${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
    throw err;
  }

  const versions = (await readVersionsFile(siteDir, pluginId)) ?? [];

  // Check if version already exists.
  if (versions.includes(version)) {
    throw new Error(
      `${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`,
    );
  }

  if (i18n.locales.length > 1) {
    logger.info`Versioned docs will be created for the following locales: name=${i18n.locales}`;
  }

  await Promise.all(
    i18n.locales.map(async (locale) => {
      const localizationDir = path.resolve(
        siteDir,
        i18n.path,
        getLocaleConfig(i18n, locale).path,
      );
      // Copy docs files.
      const docsDir =
        locale === i18n.defaultLocale

View on GitHub (pinned to 3f483e80e3)

Solutions

Choose a new, unique version tag (e.g. bump to the next semver).
If you truly want to replace it, delete the old versioned_docs/<version> and versioned_sidebars/<version>.json and remove the entry from versions.json first.

Example fix

# before
$ docusaurus docs:version 1.0.0  # 1.0.0 already exists
# after
$ docusaurus docs:version 1.1.0

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs-extra';
const versions = (await fs.readJson(versionsJsonPath).catch(() => [])) as string[];
if (versions.includes(version)) throw new Error(`Version ${version} already exists`);

Prevention

Decide version tags upstream (release script) and never reuse them.
Inspect versions.json before cutting a new version.

When it happens

Trigger: Running docs:version with a tag already present in website/versioned_docs or in the versions array returned by readVersionsFile. Triggered after validateVersionName passes and versions are read.

Common situations: Re-running the same version command twice, using a version tag you already cut, or picking a tag colliding with an earlier release.

Related errors

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