Debugging and Errors

Last updated:

Debugging code and understanding where and how to view errors is an important part of development on the HubSpot CMS. There are a number of tools you can use to increase efficiency when building and debugging and to make sure your website is optimized as you continue to build it out. 


The HubSpot CMS developer file system has many forms of validation to ensure your templates and modules render correctly on pages. 

Fatal errors

Fatal errors are errors that would prevent a page from successfully rendering. To ensure live content renders correctly, the HubSpot CMS prevents publishing templates that have fatal errors. An example of a fatal error would be missing required HubL variables, such as standard_header_includes. This will cause errors when developing in the Design Manager or when uploading files through the CMS CLI. The VS Code Extension supports HubL linting, and can display the fatal errors in-context ahead of uploading the file.

screenshot of a fatal error - design manager
screenshot of a fatal error - CMS CLI

Fatal errors must be resolved in order to publish files. 


Warnings are errors or issues which do not prevent the publishing of files. Warnings are often suggestions in syntax or potential issues a developer might be missing. The VS Code Extension supports HubL linting, and can display the warnings in-context ahead of uploading the file. For example, if you try to include a file which does not exist, this throws a warning to alert the developer.

warning - design manager

Warnings will never prevent the publishing of files, however, it is recommended to investigate warnings. 


The HubSpot CMS makes a number of optimizations to your website automatically. To learn more about them, see CDN, Security and Performance. Sometimes, debugging issues with these optimizations on a live website can be difficult. If you load a live HubSpot page with the query string ?hsDebug=true, the page will be rendered:

  • With non-minified files
  • With non-combined CSS files (individual CSS files served)
  • Without serving cached files

View HubL output

Within the Design Manager, coded files have a “Show output” toggle which open up a second code editor panel, with a transpiled code of the file you are looking at. This is helpful to see how your HubL code will transpile into CSS, HTML or JavaScript, rather than reloading live pages the file is included on. It is also a helpful tool to use when exploring new features of HubL, or learning the basics of HubL as you can easily see what your HubL input will output to. 

View HubL output

|pprint HubL filter

The |pprint HubL filter can be used on HubL variables to print valuable debugging information. It will print the type of HubL variable, which can be useful in understanding what expressions, filters, operators or functions it can be used with.

For example, {{ local_dt }} will print 2020-02-21 12:52:20. If we pretty print this variable, we can see the value is a date (PyishDate: 2020-02-21 12:52:20). This means we can use HubL filters that operate or format date objects, such as the |datetimeformat HubL filter.

{{ local_dt }}
{{ local_dt|pprint }}
{{ local_dt|datetimeformat('%B %e, %Y') }}

Developer info

Much of the data found in developer info is used internally, and is subject to change if not otherwise documented.

The developer info for a page is the context of all data available when a page is being rendered. This rendering context is all accessible via HubL. To access the developer info for a page, select the HubSpot sprocket icon in the top right hand corner of live pages > Developer Info. 

Developer info sprocket menu

This will open up a new tab that returns the rendering context for a given page in the form of JSON. It is recommended to have a JSON formatter installed in your browser to make the developer info easier to read, such as this JSON formatter Chrome extension. While much of the information contained in the page's context is for internal purposes, this tool can be valuable to see what data is available via HubL when templating.

For example, the following image is of the developer info for

Developer info example

The values of this data are being set through the Settings tab of the Content Editor:

content editor - settings

The values are then accessible to render on pages through HubL. To print the title and meta description in a base template, you would use the following HubL.

<title>{{ page_meta.html_title }}</title>
<meta name="description" content="{{ page_meta.meta_description }}">

The data in the rendering context is available through HubL, and the JSON tree can be traversed using dot notation. Data in the developer info that developers frequently print out include module field values and tags that have been exported to template context.

Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.