quasarframework/quasar · warning

SSG build failed to render SSG page:

Error message

SSG build failed to render SSG page:

What it means

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.

Source

Thrown at app-vite/lib/modes/ssg/ssg-builder.js:67

  if (onSsgRendererError === 'error') {
    return ({ err, reason, ssgPage }) => {
      console.log()
      error('SSG build failed to render SSG page:')
      console.error(ssgPage)
      error('Render error for the above SSG page:')
      console.error(err)
      error(
        `Failed to render SSG page for ${getSsgPageIdentifier(ssgPage)}.` +
          (reason ? ` ${reason}.` : '') +
          ' Check details above.'
      )
    }
  }

  if (onSsgRendererError === 'warn') {
    return ({ err, reason, ssgPage }) => {
      console.log()
      warn('SSG build failed to render SSG page:')
      console.warn(ssgPage)
      warn('Render error for the above SSG page:')
      console.warn(err)
      warn(
        `Failed to render SSG page for ${getSsgPageIdentifier(ssgPage)}.` +
          (reason ? ` ${reason}.` : '') +
          ' Check details above.'
      )
    }
  }

  if (onSsgRendererError === 'ignore') {
    return () => {}
  }

  fatal(
    'Invalid value for quasar.config.ssg.onSsgRendererError:' +
      `"${onSsgRendererError}". Must be one of: "abort", "error",` +

View on GitHub (pinned to 4841521b5f)

Solutions

1. Read the printed render error and page identifier; fix the SSR-unsafe code in the failing page/component.
2. Switch ssg.rendererOptions/onSsgRendererError to 'fail' in quasar.config during debugging so the build stops at the first error with a full stack.
3. Guard browser-only APIs (process.env.CLIENT checks, onMounted usage) or wrap the offending code in try/catch.
4. If the page should never be prerendered, exclude it via crawl-ignore or the SSG include/exclude route filters.

Example fix

// before
const data = localStorage.getItem('token')
// after
const data = process.env.CLIENT ? localStorage.getItem('token') : null

// Audit components reachable from SSG routes for browser-only API usage
grep -rn "localStorage\|window\.\|document\." src/pages src/layouts src/components

function isBrowser(): boolean {
  return typeof window !== 'undefined'
}
// usage
if (isBrowser()) localStorage.setItem('k', v)

try {
  await renderPage(ssgPage)
} catch (err) {
  console.error(`SSG render failed for ${ssgPage.path}:`, err)
  // fix code or exclude the route; with onSsgRendererError:'warn' the build continues
}

When it happens

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

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

Related errors

• Failed to render SSG page for ${getSsgPageIdentifier(ssgPage
• Failed to render ${errorsEncountered} SSG page${errorsEncoun
• Render error for the above SSG page:
• Failed to render SSG page for ${getSsgPageIdentifier(ssgPage
• quasar.config file > invalid Vite plugin specified (cannot f

AI-assisted analysis of quasarframework/quasar@4841521b5f (2026-08-30). Data as JSON: /api/errors/c0ea940285fb8bc5. Report an issue: GitHub.