facebook/docusaurus · error

Unexpected error: file at "${filePath}" does not belong to a

Error message

Unexpected error: file at "${filePath}" does not belong to any docs version!

What it means

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.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/versions/version.ts:295

    sidebarsUtils,
    categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
      docs: version.docs,
      sidebarsUtils,
    }),
  };
}

export function getVersionFromSourceFilePath(
  filePath: string,
  versionsMetadata: VersionMetadata[],
): VersionMetadata {
  const versionFound = versionsMetadata.find((version) =>
    getContentPathList(version).some((docsDirPath) =>
      filePath.startsWith(docsDirPath),
    ),
  );
  if (!versionFound) {
    throw new Error(
      `Unexpected error: file at "${filePath}" does not belong to any docs version!`,
    );
  }
  return versionFound;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Verify the offending filePath is actually inside one of the version content dirs (versioned_docs/<ver>/, docs/, or i18n paths).
2. If using symlinks, resolve them or configure Docusaurus to point at the real directory.
3. Check that versions.json and the versioned_docs folders are consistent (run docusaurus docs:version properly).
4. Report an issue if the path is legitimately in a docs dir but not matched (possible platform/path-normalization bug).

import path from 'path';
const belongs = (filePath: string, dirs: string[]) =>
  dirs.some(d => path.resolve(filePath).startsWith(path.resolve(d)));
if (!belongs(filePath, versionContentDirs)) {
  // skip or route to the correct version instead of calling getVersionFromSourceFilePath
}

try {
  const version = getVersionFromSourceFilePath(filePath, versionsMetadata);
} catch (err) {
  // log and skip files outside any version; this is an internal edge case
  console.warn('Skipping unversioned file', filePath);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${pluginIdLogPrefix}: no docs found in path=${docsDir}.
• The docs folder does not exist for version "${versionName}".
• Docs version "${versionMetadata.versionName}" has no docs! A
• Invalid version name "${name}": version name ${message}.
• ${pluginIdLogPrefix}: this version already exists! Use a ver

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