next.js: How to catch and handle errors to report logs on server side

Hi, I’m in the situation where we want to sent errors, both on server and client side, to Sentry tool.

Our app uses Express as a custom server. Basically we create an express app, apply some middlewares but delegate all the real job to the next.js handle:

  const app = nextJs({ dev: process.env.NODE_ENV !== 'production' });
  const handler = routes.getRequestHandler(app);
  const expressApp = express();

  ...
  ...

  expressApp.use(morgan('combined', { stream: logger.stream }));
  expressApp.use(statsdMiddleware);

  // Add security
  expressApp.use(helmet());

  // Sentry handler
  expressApp.use(sentry.requestHandler());

  // Load locale and translation messages
  expressApp.use(i18n);

  // Next.js handler
  expressApp.use(handler);

  // Sentry error handler.
  // MUST be placed before any other express error handler !!!
  expressApp.use(sentry.errorHandler());

With this approach next.js takes control over the rendering process and any error is catch by next.js and the only way I have to process it is overriding the _error.js page file.

Within that _error.js file I need a universal way to report errors to Sentry. Currently there are two libraries (raven for node and raven-js por javascript). The proble is I can’t import both of them because raven works for SSR but fails when webpack builds the bundle, and also raven-js fails due XMLHTTPRequest dependency too.

Is there a way I can be notified for next.js error on server side?

About this issue

  • Original URL
  • State: closed
  • Created 10 years ago
  • Reactions: 74
  • Comments: 97 (34 by maintainers)

Commits related to this issue

Most upvoted comments

introduce a hook in that catch block in client/index.js for handling this kind of error? transmit the error to an onerror/onunhandledrejection handler, if any is detected?

This is something we’ve talked about internally. And we’ll be addressing soon.

Gotta love unortodox solutions

function installErrorHandler(app) {
  const _renderErrorToHTML = app.renderErrorToHTML.bind(app)
  const errorHandler = rollbar.errorHandler()

  app.renderErrorToHTML = (err, req, res, pathname, query) => {
    if (err) {
      errorHandler(err, req, res, () => {})
    }

    return _renderErrorToHTML(err, req, res, pathname, query)
  }

  return app
}
// ¯\_(ツ)_/¯

It’s super frustrating that a basic need like this still open after 4 years and 10 major releases.

Custom logging and error handling are basic features being neglected from the Next.js team sadly 🥲

I feel like this and lack of guides/prebuilt integrations for apm and error reporting services are a big gap for next.js. I hope this is high on the roadmap. how are large companies even running next.js without these 2 basic things? I guess custom server and prayers 😢

I’m also having this problem. I wonder: would simply returning a rejected promise from next’s handleRequest be sufficient? That is, changing the code here to be:

handleRequest (req, res, parsedUrl) {
  // .....snip....

   return this.run(req, res, parsedUrl)
     .catch((err) => {
       if (!this.quiet) console.error(err)
       res.statusCode = 500
       res.end(STATUS_CODES[500])
 
       // rethrow error to create new, rejected promise 
       throw err;
     })
}

Then, in user code:

const app = nextJs({ dev: process.env.NODE_ENV !== 'production' });
const nextJsHandler = app.getRequestHandler();
const expressApp = express();

app.prepare().then(() => {
   // invoke express middlewares
   // ...

   // time to run next
   expressApp.use(function(req, res, next) {
     nextJsHandler(req, res).catch(e => {
       // use rejected promise to forward error to next express middleware
       next(e)
     })
   });

   // Use standard express error middlewares to handle the error from next
   // this makes it easy to log to sentry etc.
})

@kelly-tock okay, I wrote up a quick note about how we use preloading with NextJS: https://jake.tl/notes/2021-04-04-nextjs-preload-hack

Anyone had success catching (and handle) exceptions that occur in getServerSideProps?

It’s unclear, you’d think a framework would provide an idiomatic way to log errors both client and server 🤷‍♂️

For logging errors in the client side we have been doing the following: https://gist.github.com/jgautheron/044b88307d934d486f59ae87c5a5a5a0

It basically sends errors to the server, that are in the end printed to stdout and caught by our Docker logging driver. We have successfully caught SSR errors with react-guard with no need to override core Next files.

Install both raven (ignore with webpack as suggested in previous comments) and raven-js, then create a helper to instantiate isomorphic Raven, e.g. lib/raven.js

import Raven from 'raven-js';

// https://gist.github.com/impressiver/5092952
const clientIgnores = {
  ignoreErrors: [
    'top.GLOBALS',
    'originalCreateNotification',
    'canvas.contentDocument',
    'MyApp_RemoveAllHighlights',
    'http://tt.epicplay.com',
    "Can't find variable: ZiteReader",
    'jigsaw is not defined',
    'ComboSearch is not defined',
    'http://loading.retry.widdit.com/',
    'atomicFindClose',
    'fb_xd_fragment',
    'bmi_SafeAddOnload',
    'EBCallBackMessageReceived',
    'conduitPage',
    'Script error.',
  ],
  ignoreUrls: [
    // Facebook flakiness
    /graph\.facebook\.com/i,
    // Facebook blocked
    /connect\.facebook\.net\/en_US\/all\.js/i,
    // Woopra flakiness
    /eatdifferent\.com\.woopra-ns\.com/i,
    /static\.woopra\.com\/js\/woopra\.js/i,
    // Chrome extensions
    /extensions\//i,
    /^chrome:\/\//i,
    // Other plugins
    /127\.0\.0\.1:4001\/isrunning/i, // Cacaoweb
    /webappstoolbarba\.texthelp\.com\//i,
    /metrics\.itunes\.apple\.com\.edgesuite\.net\//i,
  ],
};

const options = {
  autoBreadcrumbs: true,
  captureUnhandledRejections: true,
};

let IsomorphicRaven = null;

if (process.browser === true) {
  IsomorphicRaven = Raven;
  IsomorphicRaven.config(SENTRY_PUBLIC_DSN, {
    ...clientIgnores,
    ...options,
  }).install();
} else {
  // https://arunoda.me/blog/ssr-and-server-only-modules
  IsomorphicRaven = eval("require('raven')");
  IsomorphicRaven.config(
    SENTRY_DSN,
    options,
  ).install();
}

export default IsomorphicRaven;

Then you can use it in your pages/_error.js and it will work both on server and client side.

import NextError from 'next/error';
import IsomorphicRaven from 'lib/raven';

class MyError extends NextError {
  static getInitialProps = async (context) => {
    if (context.err) {
      IsomorphicRaven.captureException(context.err);
    }
    const errorInitialProps = await NextError.getInitialProps(context);
    return errorInitialProps;
  };
}

export default MyError;

Hi, 2 things that I still don’t understand regarding this issue:

  1. You keep mentioning middleware as a way to solve it, but from what I see in Next.js you have to call the middleware in every API call. This is not very useful. In Express you set the middleware once on the server and it called for every request.
  2. There’re many more monitoring tools out there, you’re very focused on Sentry and give a built-in solution for integrating with this, but the platform has to give so a way for developers to customize the error handling so we’ll be able to use other tools too (Rollbar in my example).

Anyone had success catching (and handle) exceptions that occur in getServerSideProps?

I’m using Sentry.io to report errors and the solution we apply is:

1- Configure raven-node on server side 2- Configure ravenjs on client side (we made that on _document.

With this two steps we catch any unhandled exceptions both on client and server.

3- Create an _error page. Any error produced once nextjs handles the request (no matter if client or server side) that page is rendered. In the getInitialProps method of the _error page we report the error to sentry.

The way to decide how to load if raven-node or ravenjs is solved importing dynamically depending if we are in client const Raven = require('raven-js'); or server side const Raven = require('raven');. Note we have configured webpack to not bundle the raven module (the server side one) updating next.config.js with:

const webpack = require('webpack');

module.exports = {
  // Do not show the X-Powered-By header in the responses
  poweredByHeader: false,
  webpack: (config) => {
    config.plugins.push(new webpack.IgnorePlugin(/^raven$/));
    return config;
  },
};

I’ve been using @sentry/browser in the getInitialProps of _error.js and it seems to be working both client and server-side. I don’t know if @sentry/browser is supposed to have server-side support, but I am getting events to Sentry.

Though I am also calling Sentry.init() via @sentry/node in a custom Express server’s entry file, so perhaps that is setting some global state that the SSR is using.

Here’s a gist of the setup that I’m using: https://gist.github.com/mcdougal/7bf001417c3dc4b579da224b12776691

@tusgavomelo Sorry, for the late reply.

We have update. In our app we have a helper file with a method responsible to get a Raven instance taking into account if we are on client or server side.

let clientInstance;
let serverInstance;

const getRavenInstance = (key, config) => {
  const clientSide = typeof window !== 'undefined';

  if (clientSide) {
    if (!clientInstance) {
      const Raven = require('raven-js');  // eslint-disable-line global-require
      Raven.config(key, config).install();
      clientInstance = Raven;
    }

    return clientInstance;
  }

  if (!serverInstance) {
    // NOTE: raven (for node) is not bundled by webpack (see rules in next.config.js).
    const RavenNode = require('raven'); // eslint-disable-line global-require
    RavenNode.config(key, config).install();
    serverInstance = RavenNode;
  }
  return serverInstance;
};

This code runs both server side (when a request arrives) and client side. What we have done is configure webpack (next.config.js file) to avoid bundle the raven package.

_app.js is not client-side only, however componentDidCatch is

@kelly-tock if you have control of Next’s invocation, you can do this without a “custom server” using a “preload”. If you can invoke next like node -r yourCrazyPreloadMonkeyPatches.js node_modules/.bin/next you can preload arbitrarily code without losing automatic static optimization. At Notion we run Next on AWS Beanstalk and use this technique to load Datadog APM into the process, and monkey-patch global.console.log and global.console.error to use our error reporting logic.

Interesting!

There’s definitely some kind of global state going on here (which is a bit scary, and probably brittle and undesirable). Applying your changes in _error.js:

  • Without configuring Sentry in the custom server:
    • When running in development mode or production (i.e. with my app built), nothing is reported to Sentry when a server-side error occurs, but I get some ReferenceError: XMLHttpRequest is not defined error in the server logs
  • After configuring Sentry in the custom server:
    • My server-side exceptions get reported, but I also get a weird Error: Sentry syntheticException recorded in Sentry

It would be good to understand what the official solution is. Next’s docs seem to recommend using a custom <App> component now, and that’s what the “with Sentry” example does, but this only works for the client side.

a quick recap for anyone who investigating on this problem.

// pages/_error.js
import Raven from 'raven';
...
static async getInitialProps({ store, err, isServer }) {
   if (isServer && err) {
      // https://github.com/zeit/next.js/issues/1852
      // eslint-disable-next-line global-require
      const Raven = require('raven');

      Raven.captureException(err);
    }
    ...
// next.config.js
config.plugins.push(new webpack.IgnorePlugin(/^raven$/));

thanks to @acanimal 's comment.

Compact version of how to get correct Raven for node and browser w/o custom webpack config. Inspired by @acanimal comment

// package.json
"browser": {
    "raven": "raven-js"
}

// getRaven.js
const Raven = require('raven')

if (process.env.NODE_ENV === 'production') {
  Raven.config('YOUR_SENTRY_DSN').install()
}

module.exports = Raven

Gist

@kelly-tock okay, I wrote up a quick note about how we use preloading with NextJS: https://jake.tl/notes/2021-04-04-nextjs-preload-hack

thanks for writing that out but indeed we need a generic “error handler” for the server like pretty much any express.js production app will end up having so unexpected errors can be caught, a user-friendly 500 can be return and the error can be sent to any error reporting library.

fingers crossed this will be sorted out soon as it’s rather important.

@justjake Thanks for the excellent writeup! While having to monkey-patch logging is a shame, I think using --require for adding instrumentation/error handling is fairly “elegant” as far as these things go.

Sentry just released a new official Next.js SDK that has an interesting approach: it actually injects Sentry setup into the Webpack bundles for your app, both the client and server (https://github.com/getsentry/sentry-javascript/blob/master/packages/nextjs/src/utils/config.ts#L154-L155). Unfortunately, we’re using Rollbar at my company, and Rollbar doesn’t have any Next.js integration, so we’ll have to do a manual setup. The --require route seems much easier, but I wonder if maybe the Webpack solution has some other advantages I’m missing (besides not having to remember to use different command line arguments).

In general, I think Next.js docs should incorporate discussion of error reporting. I had deferred adding error handling to the “last 10% work” of a new project launch and spent yesterday in a bit of a panic trying to figure out how on earth I was going to add it. I had just assumed it’d be as easy as adding Sentry/Rollbar/Bugsnag/etc usually is - just add it to the entry point - until I realized Next has no “entry point” without a custom server. If the use of --require to register such things is the “happy path” for Next apps, I think it absolutely needs to be documented, rather than be buried here in a 4 year old GitHub issue.

I’m not sure what’s meant to be done here (why is this issue still open? What’s the plan?)

But error handling with Next was very complicated, there are a lot of use cases and places to catch errors from.

I added Sentry built-in in Next Right Now, if you’re struggling about how to configure Sentry on either backend or frontend, you might want to take a look. All Next.js errors are caught and sent to Sentry, whether client side, server side, build issue, page loading crashes, CSR crashes, etc.

If you think I missed anything, tell me!

Kinda spent a few months improving those bit by bit, should be a great starting point.

Tbh i am very confused on what the correct places to catch errors for next.js are right now. There are _app.tsx, _error.tsx and _document.tsx there are some comments saying that some stuff should be caught in _error.tsx (like: https://github.com/zeit/next.js/pull/5727/files#r235981700) but the current examples use either _app.tsx or _app and _document.

I tried both ways now and it seems that some errors that happen during ssr are not getting caught for me. Which places are now the correct ones to check for errors? The most logical one for me seems to check in the componentDidCatch of _app and the getInitialProps of the _error as this one is being served in cases of errors. I am a bit confused about the whole process.on part in the _document

Could someone with more in depth knowledge please resolve this question?

I was having a lot of trouble using the with-sentry example, so I opened up a PR for a much more simple example. It doesn’t have all the bells and whistles, but it’s been working for me.

https://github.com/zeit/next.js/pull/7119

The only thing one needs in next.js is ability to add custom middleware in next.config.js and something like next.browser.js for universal (isomorphic) plugin configuration (next.config.js is used among others for webpack configuration, which means other things defined in this file cannot be used in application code, because it would cause circular dependency).

For next.browser.js next.js could define configuration like decorator for App or Document components. This way I could implement sentry integration entirely as a plugin.

EDIT: I don’t know whether there is ticket for this, but I think @timneutkens is already extracting next server into separate packages. I think best plugin interface would be something like:


module.exports = {
  server: server => {
    server.use(Sentry.Handlers.errorHandler())
  }
}

Next.js still outputs errors to console.error on the server as long as you don’t set it to quiet.

With Sentry, you can enable autoBreadcrumbs to capture this output, and then capture your own message manually. The title will be less descriptive, but it will still contain the full stack trace.

Example implementation:

const express = require('express');
const nextjs = require('next');
const Raven = require('raven');

const dev = process.env.NODE_ENV !== 'production';

// Must configure Raven before doing anything else with it
if (!dev) {
  Raven.config('__DSN__', {
    autoBreadcrumbs: true,
    captureUnhandledRejections: true,
  }).install();
}

const app = nextjs({ dev });
const handle = app.getRequestHandler();

const captureMessage = (req, res) => () => {
  if (res.statusCode > 200) {
    Raven.captureMessage(`Next.js Server Side Error: ${res.statusCode}`, {
      req,
      res,
    });
  }
};

app
  .prepare()
  .then(() => {
    const server = express();

    if (!dev) {
      server.use((req, res, next) => {
        res.on('close', captureMessage(req, res));
        res.on('finish', captureMessage(req, res));
        next();
      });
    }

    [...]

    server.get('/', (req, res) => {
      return app.render(req, res, '/home', req.query)
    })

    server.get('*', (req, res) => {
      return handle(req, res)
    })

    server.listen('3000', (err) => {
      if (err) throw err
      console.log(`> Ready on http://localhost:${port}`)
    })
  })
  .catch(ex => {
    console.error(ex.stack);
    process.exit(1);
  });

This is a very contrived example adapted from our actual code. I haven’t tested it in this form. Let me know if it breaks.

Of course, it would still be best if Next.js could pass those errors around to Express, so that we can use the Sentry/Express integration out of the box.

@thomasboyt Thanks for pointing out Sentry released something for Next.js! I’m gonna take a look at it very soon!

For anyone interested: https://sentry.io/for/nextjs/

Also, we mentionned logging above, and we’ve released https://github.com/UnlyEd/simple-logger a few days ago, which is 1kB an universal. After trying out a lot of open source alternatives, we couldn’t find something that felt just right. Maybe you’ll find it as useful as we do!

Same to you folks. with-sentry example doesn’t allow lazy loading, as well as it doesn’t catch errors before app initialization. Moreover there are can be errors in your custom ssr server which are also want to be tracked with sentry. So these days I see such issues with setup of sentry error tracking with nextjs which are not covered by any guide:

  1. Lazy loading
  2. Errors during client\server rendering
  3. Errors raised on custom ssr server

I’ve been struggling with monkey-patching all the different parts of Next.js that log errors on the path to using Next.js for Notion’s new marketing site. It’s been a frustrating experience; I’m up to patching global.console.log = myCustomLoggingFunction at this point.

So now that we have a necessarily complex working example, what are the next steps to improve the situation:

Here are my extra notes about custom _app component and error handling:

  1. _app.js is used for ALL pages, including _error.js or pages like 404 so you really want to be sure no error is thrown when ctx.err is passed to it…
  2. Don’t forget to call Component.getInitialProps in getInitialProps of app as it’ll prevent getInitialProps of _error.js to be called (call it even if ctx.err is present)
class MyApp extends App {
  static async getInitialProps (appContext) {
    const { Component, ctx } = appContext
    if (ctx.err) {
      if (Component.getInitialProps) {
        pageProps = await Component.getInitialProps(ctx)
      }
      return { error: true, pageProps }
    }
    // here code that can throw an error, and then:
    if (Component.getInitialProps) {
      pageProps = await Component.getInitialProps(ctx)
    }
    return { pageProps }
  }
  render() {
    if (this.props.error) return super.render()
    // rest of code that can throw an error
  }
}

So far I find properly setting up error reporting in next.js a very fragile procedure 😦

@sheerun I’m hitting the same issue. Using @sentry/node isn’t trivial. The readme for this Sentry example suggests using a custom server, which we already have in the application I’m working on. To capture exceptions in our custom Express.js server, you need to insert a Sentry error handler middleware error as the first error handling middleware. If you insert Sentry’s error handler straight after the Next handler, the error has already been swallowed by that point and Sentry doesn’t see it.

The errors details are also available on the stderr stream. process.stderr.write = error => yourErrorLog(error);

@kelly-tock Next Right Now uses Sentry for monitoring (front + back + api) https://github.com/UnlyEd/next-right-now/

Running about 20 projects using Next.js (most of them using NRN) I totally feel you regarding monitoring, it’s a must-have for confidence.

Regarding logging though, I haven’t found a solution that satisfies me. I hope it comes built-in.

It’s definitely a priority! And no, you wouldn’t need a custom server:

  • The vast majority of folks aren’t using a custom server. It’s only needed if you have any very special routing requirements. i18n routing + rewrites/redirects/headers have solved most use cases for a custom server where folks previously “ejected”.
  • Most enterprise companies aren’t using API routes to connect to their database. They almost always have a separate API due to the size/scale of their teams/products. These separate APIs have their own logging/monitoring setups.
  • For large teams self-hosting wanting visibility into SSR, they capture stdout logging inside getServerSideProps and forward it to their provider of choice
  • For large teams on Vercel, most are using the Datadog Integration
  • For projects using API routes, you can use API Middlewares

Hope this helps in the meantime.

@kelly-tock Large companies using Next.js do have error handling, logging, and monitoring set up! I agree with your statement though, and we’re working on better integrations (e.g. Sentry, Datadog) with Vercel, as well as overall better guidance for “going to production” with Next.js (logging, monitoring).

Glad to hear that! I’m currently working on a proposal for switching to next, and performance monitoring and error handling will be key. Any ideas on timelines? And for both APM and error logging services, we’re left to do custom servers for now right?

Anyone had success catching (and handle) exceptions that occur in getServerSideProps?

@stephankaag

yes, something like this worked for me:

first create a middleware to handle the crash reporting. I’ve wrapped Sentry inside the CrashReporter class because simply returning Sentry will not work (i.e. req.getCrashReporter = () => Sentry).

// crash-reporter.js

const Sentry = require("@sentry/node");

class CrashReporter {
  constructor(){
    Sentry.init({ dsn: process.env.SENTRY_DSN });
  }
  captureException(ex){
    return Sentry.captureException(ex);
  }
}

function crashReporterMiddleware(req, res, next) {
  req.getCrashReporter = () => new CrashReporter();
  next();
}

module.exports = crashReporterMiddleware;

next, of course, load the middleware into your app before the Next.js request handler is set:

// server.js

const crashReporterMiddleware = require("./middleware/crash-reporter")

...

app.use(crashReporterMiddleware);

...

setHandler((req, res) => {
  return handle(req, res);
});

then wherever you call getServerSideProps:

// _error.js

export async function getServerSideProps({req, res, err}) {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404;
  const crashReporter = req.getCrashReporter();
  const eventId = crashReporter.captureException(err);
  req.session.eventId = eventId;
  return {
    props: { statusCode, eventId }
  }
}

@abraxxas process.on in _document.js is catching errors that happen on the server. As a recap,

  • _document.js is server-side only and is used to change the initial server-side rendered document markup.
  • _app.js is client-side only and is used to initialize pages.

Therefore, when an error happens on the server it should throw an error to Sentry via process.on and then the client will render the default error page or _error.js.

Hopefully this will help: https://leerob.io/blog/configuring-sentry-for-nextjs-apps/