{"record":{"id":"48f77ad543c6c894","repo":"facebook/docusaurus","slug":"docusaurus-static-site-generation-failed-for-ssg","errorCode":null,"errorMessage":"Docusaurus static site generation failed for ${ssgErrors.length} path${ssgErrors.length ? 's' : ''}:\\n- ${ssgErrors.map((ssgError) => ssgError.pathname).join('\\n- ')}","messagePattern":"Docusaurus static site generation failed for (.+?) path(.+?):\\\\n- (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/docusaurus/src/ssg/ssgGlobalResult.ts","lineNumber":65,"sourceCode":"  - ${result.warnings.join('\\n  - ')}\n`,\n      )\n      .join('\\n- ')}`;\n\n    logger.warn(message);\n  }\n}\n\nfunction throwSSGError(ssgErrors: SSGError[]): never {\n  const message = `Docusaurus static site generation failed for ${\n    ssgErrors.length\n  } path${ssgErrors.length ? 's' : ''}:\\n- ${ssgErrors\n    .map((ssgError) => logger.path(ssgError.pathname))\n    .join('\\n- ')}`;\n\n  // Note logging this error properly require using inspect(error,{depth})\n  // See https://github.com/nodejs/node/issues/51637\n  throw new Error(message, {\n    cause: new AggregateError(ssgErrors.map((ssgError) => ssgError.error)),\n  });\n}\n\nexport async function createGlobalSSGResult(\n  ssgResults: SSGResult[],\n): Promise<SSGGlobalResult> {\n  const [ssgSuccesses, ssgErrors] = _.partition(\n    ssgResults,\n    (result) => result.success,\n  );\n\n  // For now, only success results emit warnings\n  // For errors, we throw without warnings\n  printSSGWarnings(ssgSuccesses);\n\n  if (ssgErrors.length > 0) {\n    throwSSGError(ssgErrors);","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus/src/ssg/ssgGlobalResult.ts#L47-L83","documentation":"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`.","triggerScenarios":"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)`.","commonSituations":"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.","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`."],"exampleFix":"// before (component)\nfunction Page() {\n  const w = window.innerWidth; // throws in SSR\n  return <div>{w}</div>;\n}\n// after\nimport ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';\nfunction Page() {\n  const [w, setW] = useState<number>();\n  useEffect(() => setW(window.innerWidth), []);\n  return <div>{w}</div>;\n}","handlingStrategy":"try-catch","validationCode":"function isBrowserOnlyAccess(expr: string): boolean {\n  return /\\b(window|document|navigator|localStorage)\\b/.test(expr);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await buildSite();\n} catch (e) {\n  if (e.cause instanceof AggregateError) {\n    for (const inner of e.cause.errors) console.error(inner.pathname, inner.error);\n  }\n  throw e;\n}","preventionTips":["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`."],"tags":["ssg","build","ssr","rendering"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}