egg/docs/source/en/core/error-handling.md

title: Exception Handling

Exception Capture

Taking benefits from co library, Egg easily transforms asynchronous to synchronous. In the meantime, all exceptions can be caught by try catch.

With those features, you can take following implementation as reference:

// app/service/test.js
try {
  const res = yield this.ctx.curl('http://eggjs.com/api/echo', { dataType: 'json' });
  if (res.status !== 200) throw new Error('response status is not 200');
  return res.data;
} catch (err) {
  this.logger.error(err);
  return {};
}

Generally, you can use try catch to catch exceptions. However, some implementations may break this mechanism down. Imaging that yield makes generators run in order just like a chain. What will happen if one of them jumpoff the chain? The following code can help you realize the imagination:

// app/controller/jump.js
exports.buy = function* (ctx) {
  const request = {};
  const config = yield ctx.service.trade.buy(request);
  // checking the deal and don't block current request
  setImmediate(() => {
    ctx.service.trade.check(request).catch(err => ctx.logger.error(err));
  });
}

In this case, you may find that the exceptions in setImmediate will be swallowed because the scope breaks the chain, although egg already handled exceptions externally.

Above scene is also considered. To catch the exception inside the scope, You can invoke helper method ctx.runInBackground(scope) to wrap the chain back. Now, the exceptions will be detected and caught.

exports.buy = function* (ctx) {
  const request = {};
  const config = yield ctx.service.trade.buy(request);
  ctx.runInBackground(function* () {
    // Exceptions thrown here will be caught in background and printed into log.
    yield ctx.service.trade.check(request);
  });
}

For convenience of locating problems, exceptions must be guaranteed to be Error object or object based on Error object, which offers a trace of which functions were called.

Egg takes charge of exceptions

egg-onerror, one of Egg's plugin, handles all exceptions thrown in Middleware, Controller and Service, and returns the error as response based on "Accept" in request header field.

Accept	ENV	errorPageUrl	response
HTML & TEXT	local & unittest	-	onerror built-in error page
HTML & TEXT	others	YES	redirect to errorPageUrl
HTML & TEXT	others	NO	onerror built-in error page(simple, not recommended)
JSON	local & unittest	-	JSON Object with details
JSON	others	-	JSON object without details

errorPageUrl

Redirecting to your customized error page by setting errorPageUrl in onerror plugin.

onerror config in config/config.default.js:

module.exports = {
  onerror: {
    errorPageUrl: '/50x.html',
  },
};

Create your universal exception handler

Once the default handler no longer meet your needs, you still can leverage Middleware to create a new handler.

As following implementation, you can create a new file in app/middleware, for example error_handler.js:

// app/middleware/error_handler.js
module.exports = () => {
  return function* errorHandler(next) {
    try {
      yield next;
    } catch (err) {
      // `app.emit('error', err, this)` should be invoked after exceptions are caught
      // Exceptions will be caught and printed out.
      this.app.emit('error', err, this);
      // Composing the object in handler when exceptions are thrown
      this.body = {
        success: false,
        message: this.app.config.env === 'prod' ? 'Internal Server Error' : err.message,
      };
    }
  };
};

Adding your customized error_handler in config/config.default.js:

module.exports = {
  middleware: [ 'errorHandler' ],
  errorHandler: {
    // errorHandler only handle exceptions from requests under /api/, and onerror will do the same things for the rest.
    match: '/api',
  },
};

404

Egg won't take NOT FOUND from back-end as exception. Instead, if NOT FOUND is emitted without a body, it will return the following JSON object as default response.

identified as JSON:

{
  "message": "Not Found"
}

identified as HTML:

<h1>404 Not Found</h1>

Overriding default 404 page to the one you want:

// config/config.default.js
module.exports = {
  notfound: {
    pageUrl: '/404.html',
  },
};

Customize 404 Response

If you want a customized 404 response, you only need to create a middleware to handle it once, just like handling exceptions above.

// app/middleware/notfound_handler.js
module.exports = () => {
  return function* (next) {
    yield next;
    if (this.status === 404 && !this.body) {
      if (this.acceptJSON) this.body = { error: 'Not Found' };
      else this.body = '<h1>Page Not Found</h1>';
    }
  };
};

Adding yours to middleware in config:

// config/config.default.js
module.exports = {
  middleware: [ 'notfoundHander' ],
};