Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
hapi-dev-errors logo

A hapi plugin to show server errors in the browser or terminal.

Installation · Usage · Plugin Options

Build Status Known Vulnerabilities Latest Version Monthly downloads

Follow @marcuspoehls for updates!

Development of this hapi plugin is supported by Future Studio University 🚀
Join the Future Studio University and Skyrocket in Node.js


A hapi plugin to return an error view for web requests, providing more details of the issue. hapi-dev-errors will give you the exact file where the error happend and a nice error stacktrace within the browser. Skip the extra look at your command line to catch the issue's location.

hapi-dev-errors default error Youch error view

hapi-dev-errors seamlessly integrates Youch to show the error details.

Besides the web view, hapi-dev-errors prints pretty error details to the terminal. This is nice when running your hapi server as an API. Printing error details to the console is enabled by default. To disable the terminal error, use the toTerminal: false option.

hapi-dev-errors pretty terminal error


This plugin uses async/await which requires Node.js v12 or newer.


Major Release hapi.js version Node.js version
v4 >=17 hapi >=12
v3 >=17 hapi >=8
v2 >=17 hapi >=8


Add hapi-dev-errors as a dependency to your project:

npm i hapi-dev-errors

Using hapi v17 or v18?

Use the 3.x release of hapi-dev-errors:

npm i hapi-dev-errors@3

Using hapi v16 (or lower)?

Use the 1.3.2 release of hapi-dev-errors with hapi v16. Later versions are only compatible with hapi v17.

npm i hapi-dev-errors@1.3.2


Check out the examples directory and get an impression on how to configure hapi-dev-errors with the individual plugins options and how to customize the error view.


hapi-dev-errors is disabled by default to avoid leaking sensitive error details during production.

Enable the plugin by define a "truthy" value for the showErrors option.

The most straight forward way to register the hapi-dev-errors plugin:

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

// went smooth like chocolate :)

Plugin Registration Options

The following plugin options allow you to customize the default behavior of hapi-dev-errors:

  • showErrors: (boolean), default: false — by default, the plugin is disabled and keeps hapi's default error handling behavior
  • template: (string), no default — provide the template name that you want to render with h.view(template, errorData)
  • toTerminal: (boolean), default: true — print pretty errors to the terminal as well (enabled by default)
  • links: (array) - default: linked SVG icons for Google and Stack Overflow - an array of callback functions that accept the error as a parameter. The callback functions should return the link to render below the error message. Pass an empty array [] to disable the default links
await server.register({
    plugin: require('hapi-dev-errors'),
    options: {
        showErrors: process.env.NODE_ENV !== 'production',
        template: 'my-error-view',
        toTerminal: true,
        links: [ (error) => {
          return `
            <a href="${error.message}">
              Search hapi-dev-errors on GitHub

// went smooth like chocolate :)

Provided Values for Your Custom Error View

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 h.view(template, errorData).code(500).

Available properties to use in your custom error view:

  • request: the request that caused the error
  • error: the error response with all its properties
  • title: error title like Internal Server Error
  • statusCode: HTTP response status code (always 500)
  • message: error message, like Uncaught error: h.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
  • payload: HTTP request payload, only available for HTTP methods other than GET, in key-value format
  • stacktrace: error stacktrace

Feature Requests

Do you miss a feature? Please don’t hesitate to create an issue with a short description of your desired addition to this plugin.


  1. Create a fork
  2. Create your feature branch: git checkout -b my-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request 🚀


MIT © Future Studio  ·  GitHub @futurestudio  ·  Twitter @futurestud_io