GitHub v1.3.1

onError

Stable

Catches a failure during server rendering and substitutes fallback markup. The page around it still ships.

Production only.

In development and testing the error is thrown with a file path and component id so the failure is impossible to miss. onError exists to keep a production build complete, not to hide bugs while you work.

Signature

typescript
Code copied!
export function onError (context: {
  error: Error
  state: Record<string, any>
  element?: object
  page?: CoralitePage
  root?: object
}): string | { template?: string, state?: Record<string, any> } | void

export function onError (context: {
  error: Error
  state: Record<string, any>
  route: CoraliteRoute
  app: CoraliteInstance
}): string | { template?: string, state?: Record<string, any> } | null | void

The first form belongs to a component and covers that element. The second belongs to a page and covers the whole document. Both can return a string of markup, an object with template and optional state patches, or nothing.

Component boundary

When a component's render throws, Coralite looks for onError in this order: the shared function, the evaluated script metadata, then the module definition. If a fallback is returned, its markup replaces the element, state patches are merged first, and hydration is disabled for the subtree.

javascript
Code copied!
export async function server () {
  const response = await fetch('https://api.example.com/releases')
  if (!response.ok) {
    throw new Error(`Release feed responded with ${response.status}`)
  }
  return { releases: await response.json() }
}

export function onError ({ error, state }) {
  console.error('Release feed failed:', error.message)

  return {
    template: '<p class="feed-fallback">Releases are unavailable right now.</p>',
    state: { feedAvailable: false, pageTitle: state.pageTitle || 'Releases' }
  }
}

The fallback template is rendered with Coralite's normal parser and flat tokens resolved from the merged state. Custom elements inside it are compiled, so a fallback can be a real component rather than a bare string. It is not hydrated: the server output is final.

Page boundary

A page onError catches failures from the page render, including its components when they do not handle the error themselves. The returned markup becomes the page root, which makes it suitable for an outage page with the site's own header and footer.

javascript
Code copied!
export async function server ({ session }) {
  const releases = session.state.releases || []
  return { releases }
}

export function onError ({ error, route, app }) {
  app.onError({ level: 'ERROR', message: error.message, route: route.path })
  return '<main class="outage"><h1>Temporarily unavailable</h1></main>'
}

Returning null or undefined from a page boundary rethrows, which is how a page can opt out for failures that should fail the build.

Patterns

  • Third-party outage. Return cached or static guidance instead of an empty section.
  • Per-item isolation. Put the boundary on the expensive item, not the page, so one failure does not remove the surrounding content.
  • Observability. Report the error to the build's onError hook with the route and component id; the fallback markup is for visitors, the report is for you.

Do not use onError to swallow validation or type errors. Those indicate a broken component and should fail in development and in CI, where the boundary is inactive.

Diagnostics

  • CORALITE-E107 reports an onError export that is not a function.

Registration also refuses a non-function boundary, so the failure appears with the component id even if validation is skipped.