Error & Not-Found Pages
HTML and HTMX pages use the same file conventions as React, Svelte, Vue and Angular pages. Put error.html and not-found.html next to your pages, and AbsoluteJS finds them at build time.
#Files
src/frontend/html/pages/
Home.html
Home.error.html # used when Home.html fails
error.html # any other HTML page, and thrown routes
not-found.html # no route matched
src/frontend/htmx/pages/
Dashboard.html
error.html # HTMX pages, and thrown routes on HTMX requests
not-found.html # unmatched HTMX requests| File | Used when |
|---|---|
<Page>.error.html | The page with the same name fails to render |
error.html | A page fails and has no page-specific error file, or a route handler throws |
not-found.html | No route matches the request |
error.html and not-found.html may exist in both the HTML and the HTMX pages directory. That doesn't count as a page name collision.
#When They Render
These pages are HTML, so they answer page requests only: a browser navigation or an HTMX request. A client that asks for JSON, or sends Accept: */* as fetch and curl do, gets Elysia's JSON response instead.
| Request | Header | Route throws | No route matches |
|---|---|---|---|
| Browser navigation | Accept: text/html | error.html | not-found.html |
| HTMX request | HX-Request: true | HTMX error.html first | HTMX not-found.html first |
| fetch, curl or API client | application/json | JSON 500 | JSON 404 |
| Anything else | */* | JSON 500 | JSON 404 |
# GET /account with Accept: application/json (or */*)
500 application/problem+json
{"type":"internal-server-error","code":"internal-server-error","title":"Internal Server Error","status":500}
# GET /missing with Accept: application/json (or */*)
404 application/problem+json
{"type":"not-found","code":"not-found","status":404,"title":"Not Found"}#Error Pages
handleHTMLPageRequest and handleHTMXPageRequest render the error page when a page can't be served: its file is missing or unreadable, or it fails a static-page check. The response has status 500.
A route handler that throws before it returns a page also gets error.html with status 500, on a page request:
// src/backend/server.ts
export const server = new Elysia()
.use(absolutejs)
.get('/', () => handleHTMLPageRequest(asset(manifest, 'Home')))
.get('/account', () => {
throw new Error('database unavailable');
});A thrown route uses the directory's error.html, since a route isn't tied to a page file. Elysia's own errors (validation, parse errors) and thrown status(...) responses keep their own status and handling. Without an error.html in the HTML or HTMX pages directory, the route gets Elysia's default response.
The page shows the error through three placeholders. Each value is HTML-escaped.
<!-- src/frontend/html/pages/error.html -->
<!doctype html>
<html>
<head>
<title>Something went wrong</title>
<meta charset="utf-8" />
<link rel="stylesheet" href="../../styles/indexes/site.css" />
</head>
<body>
<h1>Something went wrong</h1>
<p>{{ message }}</p>
<pre>{{ stack }}</pre>
<a href="/">Back to the home page</a>
</body>
</html>AbsoluteJS looks for the error page in this order. Without any error page, the built-in AbsoluteJS error page is shown.
htmx/pages/<Page>.error.html, then htmx/pages/error.html, then the shared error page.<Page>.error.html or error.html from the first pages directory that has one, in this order: React, Svelte, Vue, Angular, Ember, HTML, HTMX. Framework pages without an error page of their own fall back to it too.htmx/pages/error.html first, then html/pages/error.html. Other page requests try them the other way round.#Dev vs Production
In development the page shows the real message and stack. Outside development it shows Something went wrong while rendering this page. and an empty stack, so no error text or file path reaches the browser. The built-in error page does the same.
# Development
<p>database unavailable</p>
<pre>Error: database unavailable
at …/src/backend/server.ts:42:11</pre>
# Production
<p>Something went wrong while rendering this page.</p>
<pre></pre>The full error is always logged on the server. When your app has no onError of its own, every route that throws is logged once with its method, path and stack, whatever the request accepts. 404s and thrown status(...) responses aren't logged.
[SSR] GET /account threw: Error: database unavailable
at …/src/backend/server.ts:42:11#Not-Found Pages
A page request that matches no route renders the first not-found page found, in this order: React, Svelte, Vue, Angular, HTML, HTMX. The status is 404.
An HTMX request tries htmx/pages/not-found.html first, so a swap that targets a missing route gets your HTMX markup.
#Custom onError
Rendering error.html for thrown routes is a fallback. If your app registers its own onError, before or after .use(absolutejs) or as a global hook in another plugin, your handler decides the response and does its own logging. AbsoluteJS doesn't render error.html for those errors or log them.
export const server = new Elysia()
.onError(({ error }) => {
console.error(error);
return new Response('Something went wrong', { status: 500 });
})
.use(absolutejs)
.get('/account', () => {
throw new Error('database unavailable');
});An onError with the default local scope inside a sub-plugin doesn't count, because Elysia doesn't share it with the app. Your handler is found when the server starts with .listen(), which covers absolute dev, absolute start and compiled binaries.
Page handler failures are separate. handleHTMLPageRequest and handleHTMXPageRequest render their error page themselves, so those responses don't depend on your onError.
#Stylesheets
Link stylesheets and scripts relative to the source file, as in your other HTML pages. The build rewrites error.html and not-found.html like any other HTML or HTMX page: links get the hashed asset URLs, and the font tags from the fonts config are added to the head. The error page is styled in production as in development.
Under secureHeaders(), inline scripts and styles in these pages get the request's nonce, like any other HTML page.