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

RequestResponse
Unknown page, e.g. /nope404, branded page inside the root layout (also on client-side navigation)
Missing file, e.g. /missing.png404 from static assets (plain text where there are none)
Unknown /api/* route404, { "error": "Not Found" }
Unexpected error in a loader or action500, 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.json under notFound (plus backToHome for the button). apps/web/pages/[...slug].tsx passes it to apps/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.html is 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 or PRODUCT_NAME; it stays English. Edit its copy and colors by hand; the colors mirror styles/theme.css, and dark mode follows the OS.
  • Expected errors: throw HTTPException from hono/http-exception with 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].tsx matches any path no other page matches. Its loader marks the request, and middleware/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.ts rewrites any text/plain 404 for a page GET (an HTML Accept or 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.tsx for 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].ts catches unknown API routes before the page does.
  • Void serves public/500.html for uncaught errors, and falls back to its own page if the file is missing.

Common Pitfalls

  • routing.fallbacks in void.config.ts never 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