facebook/docusaurus · error

Unexpected, filePath is not site-aliased: ${filePath}

Error message

Unexpected, filePath is not site-aliased: ${filePath}

What it means

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.

Source

Thrown at packages/docusaurus-utils/src/pathUtils.ts:106

export function aliasedSitePath(filePath: string, siteDir: string): string {
  const relativePath = posixPath(path.relative(siteDir, filePath));
  // Cannot use path.join() as it resolves '../' and removes
  // the '@site'. Let webpack loader resolve it.
  return `@site/${relativePath}`;
}

/**
 * Converts back the aliased site path (starting with "@site/...") to a relative path
 *
 * TODO method this is a workaround, we shouldn't need to alias/un-alias paths
 *  we should refactor the codebase to not have aliased site paths everywhere
 *  We probably only need aliasing for client-only paths required by Webpack
 */
export function aliasedSitePathToRelativePath(filePath: string): string {
  if (filePath.startsWith('@site/')) {
    return filePath.replace('@site/', '');
  }
  throw new Error(`Unexpected, filePath is not site-aliased: ${filePath}`);
}

/**
 * When you have a path like C:\X\Y
 * It is not safe to use directly when generating code
 * For example, this would fail due to unescaped \:
 * `<img src={require("${filePath}")} />`
 * But this would work: `<img src={require("${escapePath(filePath)}")} />`
 *
 * posixPath can't be used in all cases, because forward slashes are only valid
 * Windows paths when they don't contain non-ascii characters, and posixPath
 * doesn't escape those that fail to be converted.
 *
 * This function escapes double quotes but not single quotes (because it uses
 * `JSON.stringify`). Therefore, you must put the escaped path inside double
 * quotes when generating code.
 */
export function escapePath(str: string): string {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. 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.
2. If you have a raw filesystem path, convert it with aliasedSitePath(filePath, siteDir) first, then pass the result to aliasedSitePathToRelativePath.
3. If you only need a relative path, compute it directly with path.relative(siteDir, filePath) instead of round-tripping through the alias.
4. For custom plugins, prefer the higher-level APIs Docusaurus exposes for path handling rather than reaching into pathUtils internals.

Example fix

// before — passing a raw path that was never aliased
const rel = aliasedSitePathToRelativePath(rawFsPath);

// after — alias first, or compute the relative path directly
const aliased = aliasedSitePath(rawFsPath, siteDir);
const rel = aliasedSitePathToRelativePath(aliased);
// or simply:
const rel = path.relative(siteDir, rawFsPath);

if (typeof filePath !== 'string' || !filePath.startsWith('@site/')) {
  throw new Error(`Expected an @site/-aliased path, got: ${filePath}`);
}
aliasedSitePathToRelativePath(filePath);

function isAliasedSitePath(filePath: string): boolean {
  return typeof filePath === 'string' && filePath.startsWith('@site/');
}

try {
  aliasedSitePathToRelativePath(filePath);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unexpected, filePath is not site-aliased')) {
    // re-alias with aliasedSitePath(rawPath, siteDir) or compute path.relative directly
  }
  throw err;
}

When it happens

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

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

Related errors

• Can't create navigation link: no doc found with id=${docId}
• Unexpected error: file at "${filePath}" does not belong to a
• File "${relativeFilePath}" does not exist in any of these fo
• Expected output HTML file to be found at ${withTrailingSlash
• Failed to retrieve the git history for file "${file}" with u

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