404 detection Pro

Detect when a visitor hit a 404 page and fire a separate 404 event, so you can measure broken URLs without inflating your pageview counts. Works in SPAs and server-rendered apps.

Why title-based

The HTTP status code of the page isn’t available to JavaScript for any navigation after the first load, so a client-rendered 404 screen has no programmatic “this is a 404” signal beyond what you put in the DOM. The SDK uses document.title because it’s the one piece of metadata every framework and hand-rolled router already sets on 404 routes. It’s the lowest-common-denominator signal that works without integration work.

Enable

init("proj_xxx", { extensions: { notFound: true } })

// or, in React:
<Analytics projectId="proj_xxx" extensions={{ notFound: true }} />

What fires

When the title matches the pattern, a 404 event fires (in addition to the normal pageview). Properties:

Default pattern

/^(404|page not found|not found)/i

Matches titles that start with any of those phrases, case-insensitively. Generous enough for most frameworks (Next.js, React Router, SvelteKit, Nuxt) without custom config.

Custom pattern

Pass your own RegExp if your titles follow a different convention:

init("proj_xxx", {
  extensions: {
    notFound: { pattern: /missing|gone|removed/i },
  },
})

SPA navigation

The SDK wraps history.pushState, history.replaceState, and listens to popstate, so a client-side route change to a 404 screen is detected. After each navigation, the check runs on a 150ms delay so your framework has time to update document.title before we read it.

Gotchas

• If your framework updates the title later than 150ms (slow rendering, async metadata fetch), the check can miss. Use a custom pattern that matches an early-set placeholder, or fire the event yourself with track("404", { pathname: location.pathname }) from the 404 component.
• Short matches like "Not Found"can catch false positives (a blog post titled “The Lost City: Not Found”). If that bites, tighten the pattern.
• The 404event is in addition to the pageview, not a replacement. You’ll see both in Events.
• Server-rendered 404s fire on first load, client-navigated 404s fire after the 150ms settle. Same event, different timing.

Related

• Events — how to read 404 counts in the dashboard.