facebook/docusaurus · error · Error

Invalid docs option "onlyIncludeVersions": unknown versions

Error message

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

What it means

Thrown by validateVersionsOptions when onlyIncludeVersions contains names that are not available versions (computed via _.difference against availableVersionNames). Every entry must reference a real version that exists in versions.json or as 'current'.

Source

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

    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(
        `Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(
          ',',
        )}) found. ${availableVersionNamesMsg}`,
      );
    }
    if (
      options.lastVersion &&
      !options.onlyIncludeVersions.includes(options.lastVersion)
    ) {
      throw new Error(
        `Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`,
      );
    }
  }
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Match every entry to a name in the error's 'Available version names are:' list.
2. Create the missing version first with `docusaurus docs:version <name>` if it should exist.
3. Remove entries for versions you no longer ship.

Example fix

// before
docs: { onlyIncludeVersions: ['3.0', '2.0'] } // 3.0 doesn't exist
// after
docs: { onlyIncludeVersions: ['current', '2.0'] }

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

const allIncludedVersionsExist = (list: string[], available: string[]): boolean =>
  list.every(v => available.includes(v));

When it happens

Trigger: Passing onlyIncludeVersions: ['3.0'] when 3.0 isn't a version; including a typo; referencing a version before running docusaurus docs:version to create it.

Common situations: Renaming/removing versions but leaving stale entries in onlyIncludeVersions; copying a config across projects; pre-declaring a future version name that hasn't been cut yet.

Related errors

• Docs option lastVersion: ${options.lastVersion} is invalid.
• Invalid docs option "versions": unknown versions (${unknownV
• Invalid docs option "onlyIncludeVersions": an empty array is
• 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/3b4f7793b9a84b15. Report an issue: GitHub.