{"record":{"id":"74784268228525ae","repo":"facebook/docusaurus","slug":"unexpected-filepath-is-not-site-aliased-filepa","errorCode":null,"errorMessage":"Unexpected, filePath is not site-aliased: ${filePath}","messagePattern":"Unexpected, filePath is not site-aliased: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils/src/pathUtils.ts","lineNumber":106,"sourceCode":"export function aliasedSitePath(filePath: string, siteDir: string): string {\n  const relativePath = posixPath(path.relative(siteDir, filePath));\n  // Cannot use path.join() as it resolves '../' and removes\n  // the '@site'. Let webpack loader resolve it.\n  return `@site/${relativePath}`;\n}\n\n/**\n * Converts back the aliased site path (starting with \"@site/...\") to a relative path\n *\n * TODO method this is a workaround, we shouldn't need to alias/un-alias paths\n *  we should refactor the codebase to not have aliased site paths everywhere\n *  We probably only need aliasing for client-only paths required by Webpack\n */\nexport function aliasedSitePathToRelativePath(filePath: string): string {\n  if (filePath.startsWith('@site/')) {\n    return filePath.replace('@site/', '');\n  }\n  throw new Error(`Unexpected, filePath is not site-aliased: ${filePath}`);\n}\n\n/**\n * When you have a path like C:\\X\\Y\n * It is not safe to use directly when generating code\n * For example, this would fail due to unescaped \\:\n * `<img src={require(\"${filePath}\")} />`\n * But this would work: `<img src={require(\"${escapePath(filePath)}\")} />`\n *\n * posixPath can't be used in all cases, because forward slashes are only valid\n * Windows paths when they don't contain non-ascii characters, and posixPath\n * doesn't escape those that fail to be converted.\n *\n * This function escapes double quotes but not single quotes (because it uses\n * `JSON.stringify`). Therefore, you must put the escaped path inside double\n * quotes when generating code.\n */\nexport function escapePath(str: string): string {","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils/src/pathUtils.ts#L88-L124","documentation":"Thrown by aliasedSitePathToRelativePath() when the given filePath does not start with the literal prefix '@site/'. The function exists only to reverse the aliasing applied by aliasedSitePath(), so receiving a non-aliased path is a programming error in the caller, not a user-config issue. The TODO in the source acknowledges this is a workaround that the team wants to remove by refactoring away from @site aliases.","triggerScenarios":"Internal Docusaurus code passes a raw filesystem path or relative path to aliasedSitePathToRelativePath without first converting it through aliasedSitePath(). This is essentially a framework-internal invariant violation; end users normally only see it if a custom plugin/theme reaches into these utils and misuses them.","commonSituations":"A custom theme component or plugin uses aliasedSitePathToRelativePath on a path that came from elsewhere (e.g. glob results, fs reads) which never passed through aliasedSitePath. A Docusaurus version change alters which paths are aliased. String manipulation that strips or modifies the leading '@site/'.","solutions":["Confirm the value being passed actually starts with '@site/'; if it does not, it has not been aliased and should not be passed to this function.","If you have a raw filesystem path, convert it with aliasedSitePath(filePath, siteDir) first, then pass the result to aliasedSitePathToRelativePath.","If you only need a relative path, compute it directly with path.relative(siteDir, filePath) instead of round-tripping through the alias.","For custom plugins, prefer the higher-level APIs Docusaurus exposes for path handling rather than reaching into pathUtils internals."],"exampleFix":"// before — passing a raw path that was never aliased\nconst rel = aliasedSitePathToRelativePath(rawFsPath);\n\n// after — alias first, or compute the relative path directly\nconst aliased = aliasedSitePath(rawFsPath, siteDir);\nconst rel = aliasedSitePathToRelativePath(aliased);\n// or simply:\nconst rel = path.relative(siteDir, rawFsPath);","handlingStrategy":"type-guard","validationCode":"if (typeof filePath !== 'string' || !filePath.startsWith('@site/')) {\n  throw new Error(`Expected an @site/-aliased path, got: ${filePath}`);\n}\naliasedSitePathToRelativePath(filePath);","typeGuard":"function isAliasedSitePath(filePath: string): boolean {\n  return typeof filePath === 'string' && filePath.startsWith('@site/');\n}","tryCatchPattern":"try {\n  aliasedSitePathToRelativePath(filePath);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unexpected, filePath is not site-aliased')) {\n    // re-alias with aliasedSitePath(rawPath, siteDir) or compute path.relative directly\n  }\n  throw err;\n}","preventionTips":["Only call aliasedSitePathToRelativePath on values produced by aliasedSitePath.","For raw filesystem paths, use path.relative(siteDir, filePath) directly instead of round-tripping through the alias.","In custom plugins, prefer Docusaurus's higher-level path APIs over reaching into pathUtils internals."],"tags":["path","alias","internal","invariant"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}