Primate LogoPrimate
GuidesRoutes

404 fallback vs. +error.ts

Use a rest route for "not found" pages. Use +error.ts to handle errors associated with matched routes, including failures in request hooks that run before route dispatch. Only the nearest +error.ts runs; error handlers don't compose.

404 fallback ≠ error handler. The fallback only runs when nothing else matched. +error.ts runs when a matched route, layout, route hook, or earlier application request hook throws.

1) Not-found fallback (handles unmatched URLs)

Return a normal error response.

// routes/[[...path]].ts
import route from "primate/route";

export default route({
  get() {
    return new Response("Not found", { status: 404 });
  },
});

2) Error handler (handles errors associated with matched routes)

+error.ts is triggered by errors in route processing and application request hooks. If browser and API routes need different representations, inspect the request in the error handler and return HTML, JSON, or a plain response as appropriate.

// routes/+error.ts
import route from "primate/route";
import response from "primate/response";

 // or return a rendered error view

export default route({
  get() {
    return response.redirect("/");
  },
});

3) When to use which

  • Use the fallback route to show a friendly 404.
  • Use +error.ts for exceptions, timeouts, validation errors, and pre-routing request-hook failures associated with routes that did match.