Errors
createError makes an error that carries a status. It is the same function in hamur/app and hamur/server.
createError({ status = 500, message, data, fatal, cause })
A status outside 400 to 599 becomes 500. A string is also accepted and becomes the message. cause is kept as the error's cause. Without a message, the message is the status text. isHamurError(value) tells a Hamur error from any other.
Creating an error
createError({ status: 404, statusText: "Not Found", message, data }) makes the error. statusText is the status line text and defaults to the text of status; message defaults to it. data can be typed with createError<{ field: string }>(...). Nuxt's statusCode and statusMessage still work as deprecated names for status and statusText, so throw createError({ statusCode: 404 }) answers 404; in dev the first use of each logs a warning.
Where errors come from
An error thrown in a load, in route middleware or while rendering on the server shows the error page with that status. An error thrown in a handler route answers JSON { status, message, data }, or the HTML error page when the request prefers text/html. A handler called from a page or a form answers the caller with the error, as Handlers says.
A request that matches nothing is a 404: the HTML error page when the request prefers text/html, and JSON otherwise.
A path that has server routes, but none for the request's method, answers 405 with an allow header that lists the methods; see Server.
Any other error, one that is not a createError, is logged. If it has an HTTP error status or statusCode (400 to 599), the answer keeps that status; otherwise it is a 500. In production the message is the status text, such as "Internal Server Error" or "Conflict", and data is dropped. This holds for the HTML of a rendered page and for the payload the browser reads. In development the real message and the stack are shown. An error thrown after a streamed body has started cannot change the status.
The error page
app/error.tsx is the error page. It renders for every error, without a layout. Read the error with useError(), which every library provides, and leave the page with clearError.
import { clearError, useError } from "@hamur/adapter-react";
export default function ErrorPage() {
const error = useError();
return (
<main>
<h1>{error?.status}</h1>
<p>{error?.message}</p>
<button type="button" onClick={() => void clearError({ redirect: "/" })}>
Back home
</button>
</main>
);
}
The error has status, message, data and, in development only, stack. clearError() renders the current URL again; clearError({ redirect }) navigates to another URL. Without app/error.tsx each library shows a built-in page with the status, the message and a Back home link.
A failing navigation in the browser shows the error page at the new URL: middleware that throws, a load that answers an error, or an unknown layout. A page chunk that fails to load, as after a deploy, is a full page load instead. Any successful navigation clears the error.
Status helpers
notFound(message?), forbidden(message?) and unauthorized(message?) throw createError with status 404, 403 and 401; without a message it is the status text. They return never, so after if (!product) notFound() TypeScript knows product is defined. permanentRedirect(to) is redirect(to, { status: 308 }). All four are exported by hamur/app, and hamur/server has the first three.
import { forbidden, notFound, unauthorized, type Load } from "hamur/app";
const products = new Map([["1", { title: "Tea", public: true }]]);
export const load = (async ({ params, event }) => {
const product = products.get(String(params.id));
if (!product) notFound(`No product ${String(params.id)}`);
if (!event?.request.headers.get("authorization")) unauthorized();
if (!product.public) forbidden();
return { product };
}) satisfies Load;
Thrown in a load or in route middleware, on the server and in a client navigation, notFound() reaches the not-found component that covers the route, else its route boundary, else the error page. forbidden() and unauthorized() reach the route boundary that covers the route, else the error page. In a handler or a server route the error is the answer. permanentRedirect is returned from route middleware and from a load, and answers a document request with 308 and Location. See notFound and permanentRedirect.
Route boundaries
A route boundary (dash.error.tsx or dash/_error.tsx) shows the error of one route inside the page, with the layout and the parent pages above it still on screen. It reads the error with useError() and leaves with clearError(), as the error page does. It catches what the failing route's load, middleware, meta.params, meta.validate, search schema and render throw. It never catches a redirect, false or abortNavigation(), a createError({ fatal: true }), an error of a layout or the app root, or a malformed path. Those show the error page. A 404 takes the covering not-found component first, then a route boundary; any other status takes a route boundary.
page:error runs before a boundary renders, as for the error page, and on the client app:error runs too. The answer's status is the error's; an error that is not a createError is masked as above. A client navigation whose middleware, load or schema fails commits the URL and renders the boundary; the next navigation clears it.
A URL no page matches
app.notFoundMode says what answers a URL that no page matches, with status 404.
| Value | Answer |
|---|---|
"root" (default) | app/pages/_not-found.<ext>, inside the app root and the default layout; without that file, the error page |
"fuzzy" | the deepest parent page or pathless layout whose path is a prefix of the URL renders with its chain, and the not-found component that covers its children renders in its Outlet; with no such page or component, "root" applies |
The prerendered 404.html is the root not-found component when the app has one. A request that does not prefer HTML still gets the JSON 404.
Errors in the browser
An error thrown while the browser renders, which no ErrorBoundary catches and which reaches the library's root, shows the error page at the URL being rendered. Some libraries keep the page after an error that is not part of a render, such as Vue's error in an event handler or React's recoverable error; there the error page shows only for a createError({ fatal: true }).
The page:error app hook gets the error before the page renders. The app:error hook gets every error in the browser that reaches the navigator or the library's root, whether the error page shows or not. See Modules for app plugins.
Showing an error from the browser
showError(error) renders the error page at the current URL without changing the history, whatever fatal says. Use it for failures that no navigation caused. On the server, and while a navigation renders its page, it throws the error instead, so the error page answers for that URL.
import { createError, showError } from "hamur/app";
export default function Delete() {
const remove = async () => {
const response = await fetch("/api/account", { method: "DELETE" });
if (!response.ok) showError(createError({ status: response.status, message: "Could not delete the account" }));
};
return (
<button type="button" onClick={() => void remove()}>
Delete account
</button>
);
}
Error boundaries
ErrorBoundary catches errors thrown while its children render, in the browser and on the server, and renders its fallback, which receives { error, reset }. reset renders the children again.
import type { ReactNode } from "react";
import { ErrorBoundary } from "@hamur/adapter-react";
export default function Widget({ children }: { children?: ReactNode }) {
return (
<ErrorBoundary
fallback={({ error, reset }) => (
<div>
<p>{error instanceof Error ? error.message : "Something went wrong"}</p>
<button type="button" onClick={reset}>Try again</button>
</div>
)}
>
{children}
</ErrorBoundary>
);
}
The props of ErrorBoundary follow the library. In Vue the fallback is a #fallback slot with error and reset, or a fallback function prop. In Svelte it is a fallback snippet that gets { error, reset }. In html both children and fallback are functions that return a string. See Adapters.
On the server, a throwing subtree renders the fallback into the HTML, the page answers 200, and the browser hydrates in the fallback without a mismatch. reset does nothing on the server. This holds in all six libraries, with one limit:
- React: when the page streams and a suspended child fails after the first chunk was sent, the browser hydrates into the server's fallback. An
ErrorBoundarynested inside that failedSuspenseis rendered again in the browser.