{"record":{"id":"ac84c9980ec06032","repo":"facebook/docusaurus","slug":"unexpected-error-file-at-filepath-does-not-b","errorCode":null,"errorMessage":"Unexpected error: file at \"${filePath}\" does not belong to any docs version!","messagePattern":"Unexpected error: file at \"(.+?)\" does not belong to any docs version!","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-content-docs/src/versions/version.ts","lineNumber":295,"sourceCode":"    sidebarsUtils,\n    categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({\n      docs: version.docs,\n      sidebarsUtils,\n    }),\n  };\n}\n\nexport function getVersionFromSourceFilePath(\n  filePath: string,\n  versionsMetadata: VersionMetadata[],\n): VersionMetadata {\n  const versionFound = versionsMetadata.find((version) =>\n    getContentPathList(version).some((docsDirPath) =>\n      filePath.startsWith(docsDirPath),\n    ),\n  );\n  if (!versionFound) {\n    throw new Error(\n      `Unexpected error: file at \"${filePath}\" does not belong to any docs version!`,\n    );\n  }\n  return versionFound;\n}\n","sourceCodeStart":277,"sourceCodeEnd":301,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-content-docs/src/versions/version.ts#L277-L301","documentation":"Thrown by getVersionFromSourceFilePath when a source file path cannot be matched to any docs version by prefix against that version's content directories (getContentPathList). The function is used internally (e.g. during MDX/hot-reload processing) to map a file back to its version. The 'Unexpected error' prefix signals an internal/edge condition rather than a normal user-config error.","triggerScenarios":"An MDX/asset path is passed that lives outside every version's docs directory (e.g. a symlink, a generated temp file, a path from an i18n locale folder not registered, or a custom plugin feeding an arbitrary path). Also possible when version metadata is partially initialized or paths use unexpected casings/separators.","commonSituations":"Symlinks or monorepo workspaces where the resolved absolute path doesn't share a prefix with the configured docs dir; custom tooling that calls versioning internals; race during version cut; mismatched path separators on Windows.","solutions":["Verify the offending filePath is actually inside one of the version content dirs (versioned_docs/<ver>/, docs/, or i18n paths).","If using symlinks, resolve them or configure Docusaurus to point at the real directory.","Check that versions.json and the versioned_docs folders are consistent (run docusaurus docs:version properly).","Report an issue if the path is legitimately in a docs dir but not matched (possible platform/path-normalization bug)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import path from 'path';\nconst belongs = (filePath: string, dirs: string[]) =>\n  dirs.some(d => path.resolve(filePath).startsWith(path.resolve(d)));\nif (!belongs(filePath, versionContentDirs)) {\n  // skip or route to the correct version instead of calling getVersionFromSourceFilePath\n}","typeGuard":null,"tryCatchPattern":"try {\n  const version = getVersionFromSourceFilePath(filePath, versionsMetadata);\n} catch (err) {\n  // log and skip files outside any version; this is an internal edge case\n  console.warn('Skipping unversioned file', filePath);\n}","preventionTips":["Do not feed arbitrary/external paths into versioning internals; ensure they live under a version's docs dir.","Resolve symlinks before matching; normalize path separators on Windows.","Report persistent cases upstream with the exact filePath and version dirs."],"tags":["docs","versioning","internal","filesystem"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}