Custom 404 and 500 Pages in HubSpot CMS: Turn Dead Ends into Next Steps
Posted by

Custom 404 and 500 Pages in HubSpot CMS: Turn Dead Ends into Next Steps

Every site gets broken links: a mistyped URL, a deleted page, an old link in someone else's newsletter. What matters is what the visitor sees next. A bare "page not found" message ends the visit. A useful error page keeps it going. This article shows how to build and assign custom 404 and 500 pages in HubSpot CMS.

What HubSpot system pages are

HubSpot treats some pages as system pages: pages you do not publish at a URL of your choice, but that HubSpot serves in specific situations. The ones relevant here are:

  • 404 page: shown when a URL on your domain does not match any content.
  • 500 page: shown when HubSpot hits a server error while rendering a page.

Other system pages exist too, such as the password prompt, search results and email subscription pages. They are managed in the same area, so the approach below carries over.

Step 1: Create the template

You can build the page from a drag and drop template or from a coded template in the Design Manager or with the HubSpot CLI. When you create a new template, pick the template type that matches the error page, so it becomes available in the system page settings. If you work locally, keep it next to your other templates in the theme:

my-theme/
  templates/
    layouts/base.html
    system/
      404.html
      500.html

If your theme already uses a base layout (see our article on template inheritance), extend it so the error page gets the same header and footer as the rest of the site:

{% extends "../layouts/base.html" %}

{% block body %}
  <main class="error-page">
    <h1>We could not find that page</h1>
    <p>The link may be old or mistyped. Try one of these instead:</p>
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/blog">Blog</a></li>
      <li><a href="/contact">Contact us</a></li>
    </ul>
  </main>
{% endblock body %}

Adjust the block name and link targets to your own base template. Remember that every template still needs standard_header_includes and standard_footer_includes so styles, scripts and tracking load.

Step 2: Assign it to the domain

In your HubSpot account, open the website settings and look for the system page settings for your domain (the exact menu labels change over time, so check HubSpot's current knowledge base article on system pages). For each system page type, choose your template. If you have several domains, check each one, because settings can differ per domain.

What makes a good 404 page

  • Plain language. Say the page was not found and that it is not the visitor's fault.
  • Same navigation. Keep the normal header and footer so the visitor can orient themselves.
  • A few strong links. Home, your most visited sections and a contact route. Five links beat fifty.
  • A search box if your site has search.
  • Light tracking. Your analytics will show 404 page views, so you can see which broken URLs get traffic and fix them with redirects.

Keep the real status code

An error page should still be served with the 404 status. If you instead redirect lost URLs to the home page, search engines may treat them as soft errors and users never learn the link was wrong. Use the 404 page for URLs that truly have no replacement, and use URL redirects for pages that moved.

Keep the 500 page simple

A 500 page appears when something has already gone wrong, so make it light: a short apology, a link home and a contact route. Avoid depending on modules that query data (such as HubDB) or external scripts, since they may be what failed.

Testing checklist

  1. Visit a made-up URL on each domain, for example /this-page-does-not-exist, and confirm your custom page loads.
  2. Check the status code in your browser's developer tools, Network tab. It should be 404.
  3. Test on a phone-sized screen and with keyboard navigation.
  4. Click every link on the page.
  5. Review 404 traffic after a few weeks and add redirects for the most common broken URLs.

Wrap-up

A custom error page takes less than an hour to build and quietly recovers visitors you would otherwise lose. Build it from your base layout, assign it per domain, keep the real status code, and use the traffic data to fix broken links at the source.

Sources

  • HubSpot Knowledge Base: system pages and error pages for CMS Hub (check the current article for exact menu labels).
  • HubSpot Developer Documentation: templates, HubL and required includes.

Related Articles