AbsoluteJS

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

TXT
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
FileUsed when
<Page>.error.htmlThe page with the same name fails to render
error.htmlA page fails and has no page-specific error file, or a route handler throws
not-found.htmlNo 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.

RequestHeaderRoute throwsNo route matches
Browser navigationAccept: text/htmlerror.htmlnot-found.html
HTMX requestHX-Request: trueHTMX error.html firstHTMX not-found.html first
fetch, curl or API clientapplication/jsonJSON 500JSON 404
Anything else*/*JSON 500JSON 404
TXT
# 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:

TS
// 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.

HTML
<!-- 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>
{{ name }}The error's name, such as Error or TypeError. Always filled in.
{{ message }}The error message in development. A generic message in production.
{{ stack }}The stack trace in development. Empty in production.

AbsoluteJS looks for the error page in this order. Without any error page, the built-in AbsoluteJS error page is shown.

HTMX pageshtmx/pages/<Page>.error.html, then htmx/pages/error.html, then the shared error page.
HTML pages and the shared 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.
Thrown routesHTMX requests try 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.

TXT
# 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.

TXT
[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.

TS
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.