HubSpot CMS for Developers common mistakes
HubSpot CMS for Developers · Understand the traps and how to avoid them.
Writing HubL module fields with `{% if widget.label %}` style checks and assuming the value is a plain string, then rendering broken markup when the field is a choice, boolean, or rich text object.
Candidates carry over habits from older HubSpot templates where module fields behaved like flat variables, and they do not check the field type documented for each field in the module's fields.json before writing conditionals.
What to do instead
Before writing logic, identify each field's type (boolean, choice, richtext, image, link, etc.) and use the matching HubL access pattern, e.g. test a boolean directly, read a choice with module.field_name, and read a link with module.link_field.url and .href. Practice by building one module per field type and previewing each in the design manager.
Referencing `content.widgets` or bare variable names inside a module or template instead of the `module` object, producing empty output that only appears on the live page.
Older tutorial snippets and copied boilerplate use legacy variable scoping; the design manager preview can hide the problem when a default value happens to render.
What to do instead
Adopt the rule that inside a module every field is read through module.<field_name>, and inside a template read through the appropriate context variable. After editing, preview the page in a private/incognito window and check the rendered HTML source, not just the visual editor.
Building a custom module or template and forgetting to include required markup such as the `{% standard_header_includes %}` and `{% standard_footer_includes %}` tags, or omitting the `{{ content.body }}` style region, so analytics, forms, or the page editor break.
Candidates focus on the visible layout and treat HubSpot's required includes as optional boilerplate; the failure only surfaces when HubSpot scripts or the page editor are missing.
What to do instead
Memorize the required template skeleton (doctype, head with standard header includes, body with standard footer includes) and treat it as a checklist item for every new template. Verify by loading the page and confirming HubSpot's tracking script and editor toolbar are present.
Using HubL functions without the required import or with the wrong argument order, for example calling a filter or `{{ }}` expression on a value that is null, and then debugging by trial and error instead of reading the error.
HubL syntax resembles Jinja2 and Twig, so candidates assume identical behavior and skip the HubL function reference; null values from optional fields then throw template errors.
What to do instead
Keep the HubL function and filter reference open while writing, and always guard optional values with a default filter or an explicit null check before applying filters. Reproduce errors in a minimal template so the error message points to the exact line.
Hardcoding absolute URLs, colors, or copy inside templates and modules instead of exposing them as fields, then failing questions about reusable, editor-friendly components.
Candidates optimize for making the page render quickly and underestimate how heavily the exam tests modularity and marketer editability.
What to do instead
For every module, ask which values a marketer would want to change and make those fields with sensible defaults; use {{ get_asset_url() }} or relative paths for assets. Review a module and confirm no user-facing string or color is hardcoded.
Confusing HubSpot's CMS Hub tiers and the APIs available at each tier, or assuming a feature such as serverless functions or membership is available on every plan.
Candidates study features in isolation and do not build a tier matrix, so questions that hinge on plan gating trip them up.
What to do instead
Build a one-page comparison of CMS Hub Starter, Professional, and Enterprise covering serverless functions, memberships, adaptive testing, and API access, and review it before the exam. When a question mentions a feature, first ask which tier it belongs to.
Treating the CMS as only templates and ignoring the content model: blogs, hubDB tables, site pages versus landing pages, and how templates are assigned to each.
Candidates come from a front-end background and spend study time on HubL while skipping the object model, then miss questions about where content types live and which template types apply.
What to do instead
Map each content type (site page, landing page, blog post, blog listing, system template, email) to its template type and editor location, and note which support drag-and-drop areas. Create one of each in a sandbox portal and observe the differences.
Using the wrong API or endpoint for the task, for example calling the CMS Pages API when the question is about blog posts, or using the single-object endpoint with a list-style payload.
HubSpot has separate APIs for pages, blogs, hubDB, forms, and contacts, and candidates memorize endpoint names without mapping them to the content object they operate on.
What to do instead
Group endpoints by object (pages, blog posts, hubDB rows, forms submissions) and practice one create, read, update, and delete call per group in a test portal. Read the API reference's object model section rather than only the endpoint list.
Skipping authentication details, such as sending an API key as a query parameter or forgetting that private app tokens go in the Authorization header, and then failing scenario questions about secure integration.
Candidates focus on request bodies and response shapes and treat auth as a formality, while the exam tests whether they can distinguish supported auth methods and scopes.
What to do instead
Memorize that private app access tokens are sent as a Bearer token in the Authorization header, that OAuth is used for multi-account apps, and that scopes must be granted per endpoint. Practice with a private app in a sandbox and inspect the request in a tool like curl.
Ignoring performance and SEO mechanics in templates, such as missing canonical tags, unoptimized images, or render-blocking scripts, and answering questions from general web intuition rather than HubSpot-specific behavior.
Candidates treat performance as a soft topic and do not connect HubSpot features like the built-in canonical URL variable or image resizing parameters to concrete template code.
What to do instead
Learn the HubSpot-specific levers: canonical URL variables, {{ resize_image_url() }} style sizing, lazy loading attributes, and where scripts should be placed relative to standard includes. Audit one template against a checklist of these items and note the HubSpot variable used for each.