facebook/docusaurus · error · Error

Unable to get broken links for page ${pagePath}.

Error message

Unable to get broken links for page ${pagePath}.

What it means

Thrown by `getBrokenLinks` while iterating collected links for each page; the inner `getBrokenLinksForPage` threw (the original error is attached as `cause`). This is a defensive wrapper — broken-link detection itself hit an unexpected internal error computing the link set for one specific page.

Source

Thrown at packages/docusaurus/src/server/brokenLinks.ts:223

  collectedLinks: CollectedLinksNormalized;
  routes: RouteConfig[];
}): BrokenLinksMap {
  const filteredRoutes = filterIntermediateRoutes(routes);

  const helper = createBrokenLinksHelper({
    collectedLinks,
    routes: filteredRoutes,
  });

  const result: BrokenLinksMap = {};
  collectedLinks.forEach((_unused, pagePath) => {
    try {
      result[pagePath] = getBrokenLinksForPage({
        pagePath,
        helper,
      });
    } catch (e) {
      throw new Error(`Unable to get broken links for page ${pagePath}.`, {
        cause: e,
      });
    }
  });
  return result;
}

function brokenLinkMessage(brokenLink: BrokenLink): string {
  const showResolvedLink = brokenLink.link !== brokenLink.resolvedLink;
  return `${brokenLink.link}${
    showResolvedLink ? ` (resolved as: ${brokenLink.resolvedLink})` : ''
  }`;
}

function createBrokenLinksMessage(
  pagePath: string,
  brokenLinks: BrokenLink[],
): string {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Inspect `error.cause` for the real underlying failure — fixing that resolves this wrapper error.
2. Temporarily set `onBrokenLinks: 'ignore'` (or `warn`) in config to confirm the build proceeds and isolate the offending page.
3. Audit the route config of the failing `pagePath` (check the plugin that owns it) for malformed path/permalink metadata.
4. Report a Docusaurus bug with `pagePath` and the `cause` stack if the route config is valid.

Example fix

// before (docusaurus.config.js)
export default { onBrokenLinks: 'throw' }; // build aborts
// isolate first
export default { onBrokenLinks: 'warn' }; // see warnings, then fix the cause

try {
  result[pagePath] = getBrokenLinksForPage({pagePath, helper});
} catch (e) {
  throw new Error(`Unable to get broken links for page ${pagePath}.`, {cause: e});
}

When it happens

Trigger: Calling the broken-links collector (e.g. during `docusaurus build` with `onBrokenLinks` not set to `ignore`) where `getBrokenLinksForPage` throws — typically because the route/link helper encountered malformed route metadata, a missing anchor target, or an unexpected URL shape for the given `pagePath`.

Common situations: A plugin emits a route with metadata the helper cannot resolve; a page links to an anchor on a page that no longer exists in the route map; upgrading Docusaurus or a plugin exposes a previously-tolerated inconsistency; custom plugin returning unusual `permalink`/`source` values.

Related errors

• Expected output HTML file to be found at ${withTrailingSlash
• Docusaurus couldn't generate a unique hash for route ${route
• Docusaurus Bug: server bundle export from "${filename}" must
• The page component at ${path} doesn't have a default export.
• HTML minification failed (Terser)

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