hapi — Increase Development Speed With Errors in the Browser or as JSON Response

Developer tools are a minefield. We’re so picky about the tools we use and require a high quality or don’t even consider them. You have an ingrained workflow if you’re like me, you behave like a robot when starting your programming.

Being open and willing to improve your developer life is an essential skill. There’s always room for improvement and another shortcut to learn. In hapi, you’ve certainly seen the „fuzzy“ default Internal Server Error for bad implementations. You have to look at the command line to get a grasp on the actual issue.

We’ve developed hapi-dev-errors to skip the command line lookup. You’ll increase your productivity by using this elegant and expressive error view in the browser:

Better error details with hapi-dev-errors

hapi Series Overview


Install hapi-dev-errors with NPM and save the plugin as a project dependency.

# NPM v4 and below
# you’re using NPM shortcuts to (i)nstall and (-S)ave the module as a dependency
npm i -S hapi-dev-errors

# NPM v5 users, please this way
npm i hapi-dev-errors  

If you’re more into the Yarn package manager, you can use it as well.


There’s one important thing: hapi-dev-errors is turned off by default.

You need to explicitly activate it by using the showErrors option and passing a value that evaluates to a boolean true. Our recommendation is to activate the plugin based on your NODE_ENV environment variable. Make sure to not activate it in production.

await server.register({  
  plugin: require('hapi-dev-errors'),
  options: {
    showErrors: process.env.NODE_ENV !== 'production'

In production environments, hapi uses its default error handling. In case you’re changing the behavior for developer errors with HTTP status code 500, hapi-dev-errors won’t interfere. The request will is passed through without touching it.

Plugin Registration Options

At this point, there are three options that can adjust the plugin’s behavior.

  • showErrors: (boolean), default: false — activate the plugin by passing a “truthy” value when registering the plugin
  • useYouch: (boolean), default: false — use Youch to handle and display the error instead of using hapi-dev-error’s default handling
  • template: (string), no default — pass the template name that you want to render with reply.view(template, errorData)
await server.register({  
    plugin: require('hapi-dev-errors'),
    options: {
        showErrors: process.env.NODE_ENV !== 'production',
        useYouch: true,
        template: 'my-error-template'

// do the heavy lifting :)

All three options apply to requests that don’t have the Accept header set to application/json. If you’re developing your API with hapi, make sure to set the Accept: application/json HTTP header and you’ll receive a JSON object with error details.

In case you’re activating all three options at the same time, hapi-dev-errors prioritizes the error handling as follows:

  1. JSON
  2. template
  3. Youch
  4. default error handling

JSON is always the first choice. Your custom template comes next and you can delegate the error handling to Youch if you wish.

Pretty Error Handling

The following pictures illustrate the different views and responses to handle errors.

default hapi-dev-errors template hapi-dev-errors default template

hapi-dev-errors using Youch use Youch as error handler

You can also benefit from a custom view template that matches the layout of your web app.

hapi-dev-errors custom view template use a custom view template

In the following section, you’ll find all properties that are available in your custom view.

Before moving on to custom error templates, let’s look at the JSON response from hapi-dev-errors.

hapi-dev-errors JSON response Prefer JSON? No problem.

Use Your Custom Error Template

hapi-dev-errors supports the template option while registering the plugin. Provide a template name to use your personal error template and not the default one shipped with hapi-dev-errors. In case you pass a string value for the template name, the view will be rendered with reply.view(template, errorData).code(500).

Available properties to use in your custom error view:

  • title: error title like Internal Server Error
  • statusCode: HTTP response status code (always 500)
  • message: error message, like Uncaught error: reply.view(...).test is not a function
  • method: HTTP request method, like GET
  • url: URL request path, like /signup
  • headers: HTTP request headers object, in key-value format GET
  • payload: HTTP request payload, only available for HTTP methods other than GET, in key-value format
  • stacktrace: error stacktrace

Depending on the rendering engine, make use of view helper functions or JavaScript snippets to manipulate the data to your needs.

Do You Want a Feature?

Do you miss a feature? Please use the GitHub issues to create your feature request with a short description of your desired addition to this plugin.

Did you find an issue with the plugin itself, please use the GitHub issues as well :)


Improve your development flow by showing error details for bad implementations directly in the browser. Besides a nice looking web view, you can get extensive error details as a JSON response by using the Accept: application/json HTTP header.

We appreciate your feedback and would love if you leave us a comment below or tweet on Twitter @futurestud_io.

Make it rock & enjoy coding!

Mentioned Resources

  • hapi-dev-errors to return better error details and skip the look at command line to catch the issue
  • Youch — pretty error reporting in Node.js

Explore the Library

Find interesting tutorials and solutions for your problems.