Handling unhandled runtime errors

[pi0]

Nuxt 3 as a full-stack framework, has several sources of unpreventable unhandled user runtime errors that can happen in different contexts:

• Errors during the Vue rendering lifecycle (SSR + SPA)
• Errors during API or nitro server lifecycle
• Server and client startup errors (SSR + SPA)

We need a unified framework for error handling in order to:

• Allow hooking to catch error events (useful for error reporters)
• Showing errors in console or proxy to the dev tools (similar to nuxt2 window SSR logs)
• (Isomorphic) Rendering a debugging HTML page for developers
• (Isomorphic) Rendering a production HTML page for production errors and allow customization
• Rendering JSON friendly server errors
• Allow gracefully handle component level errors yet use error reporting framework
• Allow gracefully handle API errors (?)
• Handling source maps properly

For isomorphic error rendering currently, we have nuxt design templates that handle any nitro errors but the problem is that they are not isomorphic, creating a custom version is not easy and are not reactive the upside is they are pretty much lightweight as is static HTML.

To avoid the same mistake of nuxt 2 to make exactly two (html+SFC) versions of the default error design, we can simply wrap the existing HTML error to a Vue SFC and use it for isomorphic (+SPA) rendering logic. This can happen during the design packaging process.

To allow replacing default error with a user-provided component that can be reactive, isomorphic and allow using bundled assets like images and styles, we can expose an API from #app that allows rendering an error app, with the main component replaced with Error component (instead of <NuxtPage>). This solution can be universally to handle all different contexts. For the server-side, we need a nitro try/catch similar to the mechanism currently is used for HTML error rendering and for SPA unhandled errors, replacing dom. Replacing for SPA adds perf penalty but allows reusing almost the same logic that is used when capturing server/global errors and considering it should probably not happen in normal situations, an unhandled fatal SPA error is already a bad UX that needs to be gracefully handled by developers.

---

For context, Nuxt 2 error handling:

• Modules like sentry have to set up different hooks by themselves
• There is no way to handle global entry errors for platforms
• We have methods for displays errors including dev+server error page with youch, a customizable static HTML template for prod+server error pages, and a customizable error layout that is not a layout to handle dev/prod errors happening during lifecycle and not handled!
• Dev source map handling hardcoded in the core's server logic
• fetch hook errors cannot be handled and need to be handled per component with $fetchState

Related issues:

• Framework error handling Handle SVG files #156
• 404 error handling: Production build is not happend with express #2278
• Error handling with suspense Add link to nuxt/koa on README.md #282
• Nitro startup errors not handled It's not clear how to include jQuery code #356
• Cloudflare error logging 1.0 about when it can be released? Thank you #81

[harblaith7]

I wish you left us with a quick example of how this is done. The read was kind of confusing to me

[webfansplz]

Do we have any plan for this ?

[ziaadini]

any change?it's an important feature we can't SEO our site without this feature

[kissu]

How is this related to SEO?

[awacode21]

When you have fully unknown generic routes (for example coming from cms) you should use [...slug].vue for "catch-all-routes" as mentioned in the documentation: https://v3.nuxtjs.org/docs/directory-structure/pages

Obviously in that case it is up to [...slug].vue to handle errors and direct user to the error page.

In Nuxt 2 there exist a validate hook for pages, when returning false the user got redirected to error page. Also there was an error() function to navigate the user to error page.

In Nuxt 3 i currently cannot find any equivalent. I think there is currently no possibility to handle errors with "catch-all-routes" case. Which really is a problem, at least for me.

This should also be discussed here.

[Gregory-Gerard]

After some time of research, I was able to find within Nuxt how to manage this problem (which is being able to return 404s on unknown dynamic URLs, a very classic case of the web but very poorly / not documented on Nuxt 3 at the moment because not yet managed in a sustainable way, as explained in this topic)

I simply created a middleware at my page level using the definePageMeta function in my setup, making a request to my API to check the resource. If there is a problem, just throw with a specific format (see the comment with the link below to understand why), Nuxt will catch the error and handle it very well afterwards (if it's a 404 it will display the configured page correctly, same if it's a 500 for example)

Here is how I proceed :

<script setup>
import { definePageMeta } from '#imports'
import { createError } from 'h3'

definePageMeta({
  async middleware (to) {
    let data = null;

    try {
      data = (await $fetch(`${useRuntimeConfig().API_URL}/endpoint/${to.params?.id}`))?.data
    } catch (e) {
      // @see https://github.com/nuxt/framework/blob/main/packages/nitro/src/runtime/server/error.ts
      throw createError({ statusCode: e.response?.status ?? 404, statusMessage: e.response?.statusText ?? 'Not Found' })
    }

    if (!data) {
      throw createError({ statusCode: 404 })
    }
  }
})
</script>

As I said, I think it will be even better when the team specifies and documents how to do it in an "official" way, but for now this method works and seems relevant to me.

[msonowal]

Still waiting for this as while using in every pages

const { data, error } = await useFetch(url)

we have to do manually check for errors which should be in a way that we can handle as global level

[kissu]

I'm sure that the team is doing their best and kinda agreed on the priority of things, please wait a bit longer!

[danielroe]

You can follow in https://github.com/nuxt/framework/issues/2122.