Custom 404 Not-Found Handling

Introduced in: v1.0.393

Overview

The platform now renders a fully branded 404 page whenever a user navigates to a route that does not exist, follows an expired invite link, or attempts to access a deleted resource. Prior to this release, those scenarios fell through to Next.js's bare default 404 screen.

---

What Triggers the 404 Page

The custom not-found page is shown in two distinct situations:

1. Unknown Routes

Any URL path that does not match a defined route in the application automatically renders src/app/not-found.tsx. This is handled by Next.js's file-based routing convention — no additional configuration is required.

2. Token-Based Resource Lookups

Some pages accept a dynamic URL token and look up a corresponding record in the database. If the token cannot be resolved — because it has expired, been revoked, or was never valid — the page calls Next.js's notFound() helper, which triggers the same custom 404 page.

This currently applies to:

Route	Trigger
/invite/[token]	Invite token not found in the database
/agent-invite/[token]	Agent invite token not found in the database

---

What the 404 Page Shows

• Branded header and layout — consistent with the rest of the application
• Clear not-found messaging — explains that the page or resource could not be located
• Navigation links — direct links back to the dashboard so users can continue without being stranded

---

Developer Notes

Adding notFound() to New Token-Based Pages

If you create a new page that resolves a URL parameter or token against the database, call notFound() from next/navigation when the lookup returns nothing:

import { notFound } from 'next/navigation';

export default async function MyTokenPage({ params }: { params: { token: string } }) {
  const resource = await db.findByToken(params.token);

  if (!resource) {
    notFound(); // renders src/app/not-found.tsx
  }

  // ... rest of page
}

Customising the Not-Found Page

The not-found UI lives at src/app/not-found.tsx. Edit this file to update the messaging, add additional recovery links, or adjust the layout. Because it uses the root app layout, any changes to the shared layout are automatically reflected here.

---

Related Error Boundaries

This feature is part of the ERR Boundaries improvement track (control ERR-04). For other error boundary improvements, see the Changelog.