Error Pages
How 404 and 500 responses work, and how to customize them.
Unknown pages and unexpected errors get branded pages with the right HTTP status. API routes answer in JSON.
This page is part of the Configuration documentation.
What Happens
| Request | Response |
|---|---|
Unknown page, e.g. /nope | 404, branded page inside the root layout (also on client-side navigation) |
Missing file, e.g. /missing.png | 404 from static assets (plain text where there are none) |
Unknown /api/* route | 404, { "error": "Not Found" } |
| Unexpected error in a loader or action | 500, apps/web/public/500.html, no error details |
throw new HTTPException(404) from a page loader (e.g. requireActiveOrganization) | 404, the same branded page (document loads and client navigations) |
throw new HTTPException(403, { message }) | 403 with your message |
In development, Void shows its error overlay on top of the 500 page with the stack trace. In production, users never see error messages; the error and METHOD path failed with 500 are logged to Workers Logs, which apps/web/void.config.ts turns on (Operations).
Customizing
- 404 copy and look: the text is in the kit messages,
packages/i18n/src/messages/<locale>/common.jsonundernotFound(plusbackToHomefor the button).apps/web/pages/[...slug].tsxpasses it toapps/web/components/error-page-content.tsx. Edit the component (yours) for layout and buttons; leave the catch-all page's server file alone. - 500 page:
apps/web/public/500.htmlis plain HTML with inline styles, on purpose: it must render even when the app itself is broken, so it can't use components, the theme cookie, translations orPRODUCT_NAME; it stays English. Edit its copy and colors by hand; the colors mirrorstyles/theme.css, and dark mode follows the OS. - Expected errors: throw
HTTPExceptionfromhono/http-exceptionwith a 4xx status; its status and message reach the user. Errors from form actions stay with the form (form.errors).
How It Works
pages/[...slug].tsxmatches any path no other page matches. Its loader marks the request, andmiddleware/00.errors.ts(the outermost middleware) changes the status to 404, because a loader can't set the status itself.- A page loader's
HTTPException(404)would reach the browser as an empty text body.middleware/00.errors.tsrewrites anytext/plain404 for a pageGET(an HTMLAcceptor a client navigation; not/api, not a dotted path), with or without a message, to/__not-found. The catch-all answers it with the 404 page, in the URL's locale; the URL stays the same, and the cookies both passes set are kept. Don't add a page at/__not-found. - That rewrite runs the middleware again (session and memberships included): a loader 404 costs one more pass than a normal page.
- A dotted path (
/missing.png, or/pages/layout.tsxfor Vite in development) also matches the catch-all; its loader hands it to static assets (env.ASSETS). Void never falls back to assets after a route's own 404, so without that hand-off development modules would 404. routes/api/[...path].tscatches unknown API routes before the page does.- Void serves
public/500.htmlfor uncaught errors, and falls back to its own page if the file is missing.
Common Pitfalls
routing.fallbacksinvoid.config.tsnever fire: the catch-all page matches every path first. Handle rewrites in middleware instead.- A real page under a dotted path (
/docs/v1.2) must exist as its own page; unmatched dotted paths go to static assets. - Returning errors as 200 from a loader (
return { error }) hides real failures from monitoring; throw instead.
Back to: Configuration overview