facebook/docusaurus · error · Error

Invalid docs option "versions": unknown versions (${unknownV

Error message

Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}

What it means

Thrown by validateVersionsOptions when the 'versions' config object (per-version overrides like sidebar, badges, route) contains keys that are not real version names. Each key in docs.versions must correspond to an available version. Unknown keys are computed via lodash _.difference of the configured keys against availableVersionNames.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/versions/validation.ts:82

  options: VersionsOptions,
): void {
  const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(
    ', ',
  )}`;
  if (
    options.lastVersion &&
    !availableVersionNames.includes(options.lastVersion)
  ) {
    throw new Error(
      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
    );
  }
  const unknownVersionConfigNames = _.difference(
    Object.keys(options.versions),
    availableVersionNames,
  );
  if (unknownVersionConfigNames.length > 0) {
    throw new Error(
      `Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(
        ',',
      )}) found. ${availableVersionNamesMsg}`,
    );
  }

  if (options.onlyIncludeVersions) {
    if (options.onlyIncludeVersions.length === 0) {
      throw new Error(
        `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
      );
    }
    const unknownOnlyIncludeVersionNames = _.difference(
      options.onlyIncludeVersions,
      availableVersionNames,
    );
    if (unknownOnlyIncludeVersionNames.length > 0) {
      throw new Error(

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Compare the keys listed in the error against versions.json plus 'current'; remove or rename the offending keys in docs.versions.
2. If you intended a new version, run `docusaurus docs:version <x.y.z>` to materialize it before configuring it.
3. Rebuild to confirm validation passes.

Example fix

// before
docs: {
  versions: {
    '2.0': { badges: false }, // 2.0 no longer exists
  },
}
// after
docs: {
  versions: {
    'current': { badges: false },
  },
}

const available = [...JSON.parse(fs.readFileSync('versions.json','utf8')), 'current'];
const unknown = Object.keys(config.versions ?? {}).filter(k => !available.includes(k));
if (unknown.length) throw new Error(`Stale version keys: ${unknown.join(', ')}`);

const areAllVersionKeysKnown = (versions: Record<string, unknown>, available: string[]): boolean =>
  Object.keys(versions).every(k => available.includes(k));

When it happens

Trigger: Defining docs.versions['3.0'] = {...} when version 3.0 does not exist in versions.json or as the current version. Any stale entry left after a version is removed/renamed triggers it.

Common situations: Removing a versioned_docs/<ver>/ folder and its versions.json entry but leaving its config block in docusaurus.config.js docs.versions; renaming versions; migrating from a project that had different version names.

Related errors

• Docs option lastVersion: ${options.lastVersion} is invalid.
• Invalid docs option "onlyIncludeVersions": an empty array is
• Invalid docs option "onlyIncludeVersions": unknown versions
• Invalid docs option "lastVersion": if you use both the "only
• ${pluginIdLogPrefix}: this version already exists! Use a ver

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