# Error Pages

> How 404 and 500 responses work, and how to customize them.

*Canonical: https://makerkit.dev/docs/void-cloudflare/configuration/error-pages*

---

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](./overview).

## 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](../operations/logs-and-client-errors)).

## 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](./overview)
