Even the most expert developers are subject to errors when coding, making knowing how to read, debug, and resolve errors a considerable part of their job. Furthermore, when working with a CMS like HubSpot, it's essential to know where to find error logs and what tools are provided for debugging.
In this blog, we'll provide the information necessary to fully understand HubSpot's error logging and the tools you can use to debug and test your code in HubSpot.
Understanding Errors in HubSpot
The first step to debugging is, of course, knowing where HubSpot logs errors and understanding what they mean. Let's explore this in further detail.
Design Manager
When coding in the Design Manager, errors are shown in real time, indicated by a color block to the side of the code and in a collapsible list at the bottom of the interface. Module fields with errors will have an icon indicator next to the field.
Fatal Errors
A fatal error, indicated by the color red, will prevent a page from successfully rendering. It must be fixed before the asset can be published. Fatal errors can occur in situations such as leaving out required HubL variables or including miswritten HubL.
Warnings
A warning is indicated with the color yellow. It won't necessarily prevent the page from rendering, but it is highly recommended that it be investigated. A warning could be displayed in situations such as references to non-existent assets or required module fields without default content.
HubSpot CLI
When coding locally, the terminal will display fatal errors when trying to upload files and prevent an erroneous file from being uploaded.
If using VS Code, you can use the HubSpot VS Code extension to display fatal errors in the Problems tab ahead of uploading the file.
Warnings are not accounted for when using the HubSpot CLI and would require checking the files in the Design Manager.
If you are writing module or theme fields using HubSpot’s JavaScript fields functionality, the errors returned are less detailed. In this case, it’s better to use the hs cms convert-fields command to first convert to JSON and then attempt to upload to receive a more detailed error.
Page Editor
The Page Editor specifically calls out erroneous content in a page's settings, modules, and sections. While this is typically helpful information for not missing any required content, it can also be used to debug incorrectly formatted module fields and template defaults.
Code Alerts
When logged in and viewing a page, click the HubSpot Tools sprocket button to navigate to Code Alerts or go directly to https://app.hubspot.com/code-alerts/. This dashboard lists all live errors in the portal, listed by the page on which the erroneous assets are being used. When hovering over a listed error, you can choose to:
- Open the asset in the design manager.
- View a detailed syntax error.
- View the debug info on the listed page.
Debugging Tools
When your website has errors that are more than a typo, you might need to look deeper. HubSpot provides several tools to help you get into the nitty-gritty of your templates, modules, and even your portal's data.
Three of the tools we’ll address (Bust Cache, Debug Mode, and Developer Mode) can be more easily used through the HubSpot Developer Extension, a browser extension of useful shortcuts for HubSpot developers.
Bust Cache
Made a fix but it doesn’t seem to be taking? It might be that your browser’s cache is keeping your webpage from updating to the newest version of your files. By adding ?hsBustCache=[random#] to the end of a URL, you can force the browser to show a cleared cache version of the page.
Debug Mode
Add ?hsDebug=true to the end of a URL to render pages with non-minified and uncombined files, bust cache, and render debugging information in the browser developer tools.
The debugging information will provide a breakdown of rendering request timing, whether the page can be prerendered, and the reasons if not, and also display errors and warnings right in the page source.
Developer Mode
Developer Mode is a tool used within HubSpot’s page editor rather than on a live URL. By adding ?developerMode=true to the page editor URL, it’ll add three helpful extensions to the editor:
- An Open in Design Manager link on all modules so that you can go directly to the code of a module.
- A Reset content button to reset content to its default state.
- A Show all Rows toggle, which will let you view and edit the dnd_rows on the page.
Developer Info
When logged in and visiting a page, you can click the HubSpot Tools sprocket button to navigate to the Developer Info for that page. The Developer Info is JSON-formatted data of all available data when a page is rendering, which can be accessed using HubL. This includes data such as contact and company information, portal settings, buffer modes, template assets, theme properties, and much more.
Not only is this useful for finding if you're referencing a specific data set correctly, but it can also help you understand exactly what data you can access and use within your templates.
To better view this data, it is recommended to have a JSON formatter extension installed on your browser.
HubL
Lastly, the HubL coding language itself can be used for debugging using filters such as |tojson and |pprint. |pprint can be used to print what type a variable is while |tojson can return variable and module field data in a JSON format.
Environments
Please note: when debugging a live website, it could be detrimental to do testing on the live site itself, as something could break further while testing, or testing might require outputting data on the page that shouldn’t be visible normally. Using different environments inside HubSpot, like Content Staging or a Sandbox environment, will allow debugging with peace of mind. Let’s get into more detail.
Design Manager Preview
Debugging a module or template can be tricky because any changes published to the asset will immediately publish to any pages currently using those assets. However, if coding in the Design Manager, changes can be Previewed without publishing simply by clicking the Preview button in the top right corner of the interface.
Previewing modules will open an interface with display options at the top, a sidebar to test your fields, and a preview panel of the rendered output.
Previewing templates provide two options: to preview with or without display options.
Draft
If the debugging requires testing something, such as multiple modules working together or the usability of a template, it might require an actual page to work with. This is where simply Drafting a page could come in handy. Creating a page and leaving it in Draft is a quick and easy way to test page settings, modules, and templates available to all portals.
However, remember that any changes published to a module or template will also be visible on any published pages using these assets. If an asset needs to be debugged while being used on a page, make a clone of it in the Design Manager and do the debugging with the clone.
Content Staging
Available to Professional and Enterprise portals, Content Staging is quite similar to creating pages in Draft but with the added benefit of being able to stage already existing pages. Upon publishing that staged page, the existing page will be updated. Staging is particularly great if you need to completely rework an existing page or update multiple pages, such as in the case of a site-wide redesign.
Sandbox
Available to Enterprise users only, a sandbox account can be created to thoroughly test all aspects of a portal (assets, data, workflows, integrations, etc.) without affecting any live content. However, remember that the sandbox is a one-way sync from Production to Sandbox. Once testing has been completed, the solution must be duplicated within the Production portal.
Master HubSpot Debugging Today
Debugging is essential for any developer working with HubSpot or any other CMS. You can efficiently identify and resolve issues in your code by understanding the various error types, knowing where to find them, and utilizing the powerful debugging tools provided by HubSpot. From the Design Manager and HubSpot CLI to Content Staging and Sandbox environments, HubSpot offers a comprehensive suite of debugging tools to ensure your websites and applications run smoothly.
Are you struggling with debugging your HubSpot projects or need expert assistance to optimize your HubSpot development workflow? Reach out to the Lynton team. Our team of experienced HubSpot developers is ready to help you tackle any coding issues and improve your development process!
You May Also Like
