Building Your App

Error Handling

Custom 404 and 500 pages with special files.

Two special files at the root of app/ control the non-happy paths:

not-found.tsx - rendered with status 404 for unmatched routes
error.tsx - rendered with status 500 when a page render throws

Both render through your normal layout pipeline (root layout included), server-side. If neither exists, GioJS serves clean built-in pages instead.

tsx

// app/not-found.tsx
export default function NotFound() {
  return <div><h1>404</h1><p>Page not found.</p></div>;
}

The error page receives the failure via props. The message is worth showing only in development:

tsx

// app/error.tsx
export default function Error({ error }: { error?: { message: string } }) {
  return (
    <div>
      <h1>Something went wrong</h1>
      {process.env.NODE_ENV === 'development' && <pre>{error?.message}</pre>}
    </div>
  );
}

Static export

gio export writes your 404 page (or the built-in default) to out/404.html, which static hosts like Cloudflare Pages, GitHub Pages, and Netlify serve with a real 404 status for unknown URLs - without it, many hosts fall back to the home page with a 200.

API routes

Errors thrown in route.ts handlers are logged server-side and answered with a JSON 500 - internal details never reach the client. Requests for methods a handler file doesn't export get 405 with an Allow header.