Product
PublishingMembershipsIntegrationsThemesCustomersPricing
Developers
DocumentationInstall / SetupTheme DocsAPI Reference
Resources
About UsHelp CenterCommunity ForumProduct Updates

API ReferenceHandlebars Themes

  • API v3 (latest)
  • API v2

    • Error

    Error templates used for all 4xx and 5xx errors that may arise on a site

    Description

    Ghost can throw errors, most common being a 404 error. Depending on the complexity of your theme, your routes file and other factors errors can range from 4xx to 5xx. Read more about error status codes on MDN.

    Routes

    Errors can be rendered on any route.

    Templates

    The default template for an error is error.hbs, this will be used to render any error if there are no specific templates provided.

    Error classes, 4xx and 5xx, can be captured using error-4xx.hbs and error-5xx.hbs respectively. For example a 404 error can be captured with error-4xx.hbs, and a 500 error can be captured with error-5xx.hbs.

    Specific errors can be captured by naming the template with the status code. For example 404 errors can be captured using error-404.hbs.

    If no custom error templates have been defined in the theme Ghost will use it's default error template, which is shown in the example below.

    Data

    Error templates have access to the details of the error thrown. Attributes are listed below:

    Error object attributes

    • {{statusCode}}: The HTTP status code of the error
    • {{message}}: The error message
    • {{errorDetails}}: An object containing further error details

    errorDetails object attributes

    • {{rule}}: The rule
    • {{ref}}: A reference
    • {{message}}: Further information about the issue captured

    Helpers

    Error templates should not use any theme helpers, with the exception of {{asset}}. It also should not extend the default template, to further avoid the use of template helpers. Using theme helpers inside error templates can lead to misleading error reports.

    The only error template that is permitted to use helpers, and ergo template inheritance, is the error-404.hbs template file for capturing 404 errors. This is due to the 404 error being a common error to see on a typical site.

    Example Code

    error.hbs
    <!doctype html>
<!--[if (IE 8)&!(IEMobile)]><html class="no-js lt-ie9" lang="en"><![endif]-->
<!--[if (gte IE 9)| IEMobile |!(IE)]><!--><html class="no-js" lang="en"><!--<![endif]-->
  <head>
    <meta http-equiv="Content-Type" content="text/html" charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />

    <title>{{statusCode}} — {{message}}</title>

    <meta name="HandheldFriendly" content="True">
    <meta name="MobileOptimized" content="320">
    <meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1, maximum-scale=1">
    <meta name="apple-mobile-web-app-capable" content="yes" />

    <link rel="shortcut icon" href="{{asset "favicon.ico"}}">
    <meta http-equiv="cleartype" content="on">

    <link rel="stylesheet" href="{{asset "public/ghost.css" hasMinFile="true"}}"/>

  </head>
  <body>
    <main role="main" id="main">
      <div class="gh-app">
          <div class="gh-viewport">
              <div class="gh-view">
                <section class="error-content error-{{statusCode}} js-error-container">
                  <section class="error-details">
                    <section class="error-message">
                      <h1 class="error-code">{{statusCode}}</h1>
                      <h2 class="error-description">{{message}}</h2>
                      <a class="error-link" href="{{@site.url}}">Go to the front page →</a>
                    </section>
                  </section>
                </section>

                {{#if errorDetails}}
                    <section class="error-stack">
                        <h3>Theme errors</h3>

                        <ul class="error-stack-list">
                            {{#foreach errorDetails}}
                                <li>
                                    <em class="error-stack-function">{{{rule}}}</em>

                                    {{#foreach failures}}
                                        <p><span class="error-stack-file">Ref: {{ref}}</span></p>
                                        <p><span class="error-stack-file">Message: {{message}}</span></p>
                                    {{/foreach}}
                                </li>
                            {{/foreach}}
                        </ul>
                    </section>
                {{/if}}
              </div>
          </div>
      </div>
    </main>
  </body>
</html>
    Contexts & Templates

    Tag

    Functional Helpers

    Overview