onError
Catches a failure during server rendering and substitutes fallback markup. The page around it still ships.
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
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.
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.
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
onErrorhook 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-E107reports anonErrorexport 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.
Related
- server for the failures most likely to reach this boundary.
- Pages reference for the page export contract.
- Validation guide for failures that should not be caught.