Suggestion: unauthorized() and forbidden() error handling APIs (like notFound())

[fellipeutaka]

Hi! First of all, thank you for the amazing work on TanStack Router. The flexibility and DX are really impressive! 🙌

I'm here to ask for your thoughts on a potential feature to improve how we handle common HTTP errors like 401 Unauthorized and 403 Forbidden — similarly to how notFound() is currently supported.

---

📌 Problem

Right now, the router offers great ergonomics for redirects and not-found cases using throw redirect() and throw notFound(), and lets us define a notFoundComponent to display friendly UI when a 404 occurs.

However, handling other frequent errors like 403 Forbidden and 401 Unauthorized typically requires custom logic in an errorComponent, for example:

if (error.status === 403) {
  return <p>You don’t have permission to view this page.</p>
}

This works, but requires extra boilerplate and logic inside a error boundary.

---

✅ Proposal

Introduce new functions similar to notFound():

• throw unauthorized()
• throw forbidden()
• Optional route-level components:
  • unauthorizedComponent
  • forbiddenComponent

Example:

export const Route = createFileRoute('/settings')({
  loader: async () => {
    const result = await getSettings()
    if (result.error) {
      if (result.error.status === 403) throw forbidden()
      if (result.error.status === 401) throw unauthorized()
      throw result.error
    }
    return result.data
  },
  component: () => {
    return (
      <div>
        <p>Settings page</p>
        <Outlet />
      </div>
    )
  },
  forbiddenComponent: () => {
    return <p>You don't have permission to see this page!</p>
  },
  unauthorizedComponent: () => {
    return <p>You must be logged in to access this page.</p>
  },
})

This would allow for a more declarative and composable approach to common authorization errors, without pushing all logic into a global error handler.

---

🔍 Inspiration

This idea is inspired by the experimental unauthorized and forbidden file conventions in Next.js 15.1+, where calling unauthorized() or forbidden() during rendering triggers a specific UI file and returns appropriate status codes (401 or 403):

• unauthorized() + app/unauthorized.tsx
• forbidden() + app/forbidden.tsx

// app/unauthorized.tsx
export default function UnauthorizedPage() {
  return (
    <main>
      <h1>401 - Unauthorized</h1>
      <p>Please log in to access this page.</p>
    </main>
  )
}

// app/forbidden.tsx
export default function ForbiddenPage() {
  return (
    <main>
      <h1>403 - Forbidden</h1>
      <p>You are not authorized to access this resource.</p>
    </main>
  )
}

It’s a neat pattern that keeps intent explicit and decouples the rendering of error states from the rest of the app.

---

💬 Question

Would something like this make sense within TanStack Router’s design principles?

I’d love to hear your thoughts and see if this aligns with the router’s goals. If it does, I’d be happy to help brainstorm the API further or even contribute.

Thanks again for your work — and for considering the suggestion!

[rnkdsh]

good idea