The global error (_global-error)

The error UIs of the routes answer errors inside a route. When the app itself fails to render (the root layout, the providers in src/app.tsx), no route is on screen to answer, so the whole document is replaced. src/routes/_global-error.tsx at the routes root is that document. It has no URL (it is not a route), and two such files are a scan error.

// src/routes/_global-error.tsx
export const metadata = { title: "Example could not load", robots: { index: false } };
export default function GlobalError({ error, reset }) {
  return (
    <html lang="en">
      <body>
        <h1>Application error</h1>
        <p>{error.message}</p>
        <button onClick={reset}>Retry</button>
      </body>
    </html>
  );
}

• Server. A failure before the document starts is answered with this document: status 500, its own <html> and <body>, the public error (the reason phrase in production, so the original message never reaches the page), the module's metadata as the head, and Cache-Control: no-store. HEAD answers 500 with no body. reset does nothing on the server: the answer carries no script.
• Browser. hydrateDusk({ routes, App, globalError }) takes the module. When the app fails to mount, the page is requested again, so the server answers this document (it has no script, so it does not mount again). A second failure in the same session is not retried, and the error stays reported (onError). reset reloads the page. The browser does not draw the document itself: the DOM renderer cannot build <html> and <body> from JSX.
• Without the file, the built-in 500 page answers, as before. The handler option globalError needs pages().