facebook/docusaurus · critical · Error

Docusaurus static site generation failed for ${ssgErrors.len

Error message

Docusaurus static site generation failed for ${ssgErrors.length} path${ssgErrors.length ? 's' : ''}:\n- ${ssgErrors.map((ssgError) => ssgError.pathname).join('\n- ')}

What it means

Thrown by `throwSSGError` at the end of static site generation when one or more routes failed to render. It aggregates per-path failures into a single message and wraps the underlying errors in an `AggregateError` as `cause`. This is the top-level 'build failed' error for `docusaurus build`.

Source

Thrown at packages/docusaurus/src/ssg/ssgGlobalResult.ts:65

  - ${result.warnings.join('\n  - ')}
`,
      )
      .join('\n- ')}`;

    logger.warn(message);
  }
}

function throwSSGError(ssgErrors: SSGError[]): never {
  const message = `Docusaurus static site generation failed for ${
    ssgErrors.length
  } path${ssgErrors.length ? 's' : ''}:\n- ${ssgErrors
    .map((ssgError) => logger.path(ssgError.pathname))
    .join('\n- ')}`;

  // Note logging this error properly require using inspect(error,{depth})
  // See https://github.com/nodejs/node/issues/51637
  throw new Error(message, {
    cause: new AggregateError(ssgErrors.map((ssgError) => ssgError.error)),
  });
}

export async function createGlobalSSGResult(
  ssgResults: SSGResult[],
): Promise<SSGGlobalResult> {
  const [ssgSuccesses, ssgErrors] = _.partition(
    ssgResults,
    (result) => result.success,
  );

  // For now, only success results emit warnings
  // For errors, we throw without warnings
  printSSGWarnings(ssgSuccesses);

  if (ssgErrors.length > 0) {
    throwSSGError(ssgErrors);

View on GitHub (pinned to 3f483e80e3)

Solutions

Inspect the `cause` AggregateError — each entry's `pathname` and inner `error` pinpoint the failing page.
Wrap browser-only code in `typeof window !== 'undefined'` or `ExecutionEnvironment.canUseDOM`.
Fix the data/component for the listed path; rebuild.
For memory issues, reduce concurrency / raise Node heap: `NODE_OPTIONS=--max-old-space-size=8192`.

Example fix

// before (component)
function Page() {
  const w = window.innerWidth; // throws in SSR
  return <div>{w}</div>;
}
// after
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
function Page() {
  const [w, setW] = useState<number>();
  useEffect(() => setW(window.innerWidth), []);
  return <div>{w}</div>;
}

Defensive patterns

Strategy: try-catch

Validate before calling

function isBrowserOnlyAccess(expr: string): boolean {
  return /\b(window|document|navigator|localStorage)\b/.test(expr);
}

Try / catch

try {
  await buildSite();
} catch (e) {
  if (e.cause instanceof AggregateError) {
    for (const inner of e.cause.errors) console.error(inner.pathname, inner.error);
  }
  throw e;
}

Prevention

Guard all browser-only APIs with `typeof window !== 'undefined'` or `ExecutionEnvironment.canUseDOM`.
Render-test pages with sample data before deploying.
Keep `docusaurus build` in CI to catch SSR errors pre-merge.
Raise Node heap for large sites: `NODE_OPTIONS=--max-old-space-size=8192`.

When it happens

Trigger: During `docusaurus build`, the SSG renderer throws for specific paths (React render error, missing import, runtime exception in a component). `createGlobalSSGResult` partitions results; any failure triggers `throwSSGError(ssgErrors)`.

Common situations: A page imports a module that doesn't exist; a component throws on certain data (e.g. undefined frontmatter); browser-only APIs (`window`, `document`) accessed during SSR without guards; memory exhaustion on large sites.

Related errors

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