{"record":{"id":"a28956377576e478","repo":"facebook/docusaurus","slug":"invalid-docs-option-versions-unknown-versions","errorCode":null,"errorMessage":"Invalid docs option \"versions\": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}","messagePattern":"Invalid docs option \"versions\": unknown versions \\((.+?)\\) found\\. (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/versions/validation.ts","lineNumber":82,"sourceCode":"  options: VersionsOptions,\n): void {\n  const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(\n    ', ',\n  )}`;\n  if (\n    options.lastVersion &&\n    !availableVersionNames.includes(options.lastVersion)\n  ) {\n    throw new Error(\n      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,\n    );\n  }\n  const unknownVersionConfigNames = _.difference(\n    Object.keys(options.versions),\n    availableVersionNames,\n  );\n  if (unknownVersionConfigNames.length > 0) {\n    throw new Error(\n      `Invalid docs option \"versions\": unknown versions (${unknownVersionConfigNames.join(\n        ',',\n      )}) found. ${availableVersionNamesMsg}`,\n    );\n  }\n\n  if (options.onlyIncludeVersions) {\n    if (options.onlyIncludeVersions.length === 0) {\n      throw new Error(\n        `Invalid docs option \"onlyIncludeVersions\": an empty array is not allowed, at least one version is needed.`,\n      );\n    }\n    const unknownOnlyIncludeVersionNames = _.difference(\n      options.onlyIncludeVersions,\n      availableVersionNames,\n    );\n    if (unknownOnlyIncludeVersionNames.length > 0) {\n      throw new Error(","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/versions/validation.ts#L64-L100","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Compare the keys listed in the error against versions.json plus 'current'; remove or rename the offending keys in docs.versions.","If you intended a new version, run `docusaurus docs:version <x.y.z>` to materialize it before configuring it.","Rebuild to confirm validation passes."],"exampleFix":"// before\ndocs: {\n  versions: {\n    '2.0': { badges: false }, // 2.0 no longer exists\n  },\n}\n// after\ndocs: {\n  versions: {\n    'current': { badges: false },\n  },\n}","handlingStrategy":"validation","validationCode":"const available = [...JSON.parse(fs.readFileSync('versions.json','utf8')), 'current'];\nconst unknown = Object.keys(config.versions ?? {}).filter(k => !available.includes(k));\nif (unknown.length) throw new Error(`Stale version keys: ${unknown.join(', ')}`);","typeGuard":"const areAllVersionKeysKnown = (versions: Record<string, unknown>, available: string[]): boolean =>\n  Object.keys(versions).every(k => available.includes(k));","tryCatchPattern":null,"preventionTips":["When removing a version, also delete its docs.versions entry in the same commit.","CI-check that every docs.versions key appears in versions.json or equals 'current'."],"tags":["docs","versioning","config-validation"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}