{"record":{"id":"c0ea940285fb8bc5","repo":"quasarframework/quasar","slug":"ssg-build-failed-to-render-ssg-page","errorCode":null,"errorMessage":"SSG build failed to render SSG page:","messagePattern":"SSG build failed to render SSG page:","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"app-vite/lib/modes/ssg/ssg-builder.js","lineNumber":67,"sourceCode":"  if (onSsgRendererError === 'error') {\n    return ({ err, reason, ssgPage }) => {\n      console.log()\n      error('SSG build failed to render SSG page:')\n      console.error(ssgPage)\n      error('Render error for the above SSG page:')\n      console.error(err)\n      error(\n        `Failed to render SSG page for ${getSsgPageIdentifier(ssgPage)}.` +\n          (reason ? ` ${reason}.` : '') +\n          ' Check details above.'\n      )\n    }\n  }\n\n  if (onSsgRendererError === 'warn') {\n    return ({ err, reason, ssgPage }) => {\n      console.log()\n      warn('SSG build failed to render SSG page:')\n      console.warn(ssgPage)\n      warn('Render error for the above SSG page:')\n      console.warn(err)\n      warn(\n        `Failed to render SSG page for ${getSsgPageIdentifier(ssgPage)}.` +\n          (reason ? ` ${reason}.` : '') +\n          ' Check details above.'\n      )\n    }\n  }\n\n  if (onSsgRendererError === 'ignore') {\n    return () => {}\n  }\n\n  fatal(\n    'Invalid value for quasar.config.ssg.onSsgRendererError:' +\n      `\"${onSsgRendererError}\". Must be one of: \"abort\", \"error\",` +","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/quasarframework/quasar/blob/4841521b5f635a971eb9e2710e5542efd194691b/app-vite/lib/modes/ssg/ssg-builder.js#L49-L85","documentation":"Warning logged during an SSG build when the onSsgRendererError option is set to 'warn' and the headless renderer failed to prerender an SSG page. The handler prints the offending page, the render error, and a page identifier so the build can continue while surfacing which route failed. It does not throw; the build completes but that page may be missing or degraded in the output.","triggerScenarios":"During `quasar build -m ssg`, the renderer throws for a specific ssgPage (e.g. SSR runtime error in the page component) while ssgConfig.onSsgRendererError === 'warn'. The handler returned by getSsgRendererErrorHandler is invoked with { err, reason, ssgPage }.","commonSituations":"A route component accessing browser-only APIs (window, localStorage) without guards; an async setup() that rejects on the server; a plugin that crashes during SSR; importing a module unsupported in Node.","solutions":["Read the printed render error and page identifier; fix the SSR-unsafe code in the failing page/component.","Switch ssg.rendererOptions/onSsgRendererError to 'fail' in quasar.config during debugging so the build stops at the first error with a full stack.","Guard browser-only APIs (process.env.CLIENT checks, onMounted usage) or wrap the offending code in try/catch.","If the page should never be prerendered, exclude it via crawl-ignore or the SSG include/exclude route filters."],"exampleFix":"// before\nconst data = localStorage.getItem('token')\n// after\nconst data = process.env.CLIENT ? localStorage.getItem('token') : null","handlingStrategy":"try-catch","validationCode":"// Audit components reachable from SSG routes for browser-only API usage\ngrep -rn \"localStorage\\|window\\.\\|document\\.\" src/pages src/layouts src/components","typeGuard":"function isBrowser(): boolean {\n  return typeof window !== 'undefined'\n}\n// usage\nif (isBrowser()) localStorage.setItem('k', v)","tryCatchPattern":"try {\n  await renderPage(ssgPage)\n} catch (err) {\n  console.error(`SSG render failed for ${ssgPage.path}:`, err)\n  // fix code or exclude the route; with onSsgRendererError:'warn' the build continues\n}","preventionTips":["Use process.env.CLIENT / onMounted guards around browser-only APIs.","Test prerendering locally with onSsgRendererError:'fail' to catch issues early.","Keep heavy browser logic out of setup() executed during SSR.","Exclude truly client-only routes from the SSG crawl."],"tags":["ssg","ssr-render-error","build","prerender"],"backgroundTag":"ssg-page-render-failed","analyzedSha":"4841521b5f635a971eb9e2710e5542efd194691b","analyzedAt":"2026-08-30T01:13:14.944Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}