Troubleshooting

The problems buyers actually meet, each with its cause and its fix.

Updated August 23, 2026 · 7 min read · Applies from version 1.0.0

Most issues with a new theme come from the handful of things a theme file cannot carry: your forms, your video, your menus, your blog's existing content. Find your symptom below.

Blog

The blog listing page keeps the old theme's content

Symptom. The listing page uses Mistral Pro's header, footer and styles, but its body still shows the modules of the previous theme.

Cause. A drag-and-drop page's saved content belongs to the page, not to the template. When you switch the listing template, HubSpot keeps the content the page already had — which is the right behaviour for a theme change, but leaves the old modules in place. The blog is correctly bound to the Mistral Pro template; only the body is stale.

Fix. Settings → Content → Blog → Templates → Blog listing page → Edit page. Delete the old modules and drop in the template's own, in this order: Two-tone section heading, Featured blog post banner, Blog posts grid with topic filters and pagination, Newsletter signup band, Dark call to action banner. Pick your newsletter form, set the heading, publish. Alternatively, create a new blog choosing Mistral Pro's listing and post templates at creation, then move your posts to it.

A blog module shows a placeholder or nothing

Cause. The selected blog has no published post, or the module points at the wrong blog. Select a blog in the Blog field means "the account's default blog".

Fix. Publish at least one post, or pick the right blog in the module's Source group. For Posts carrying a given tag, check the tag slugs (comma-separated). For the Featured blog post banner pointed at a post by URL or slug, increase Lookup depth if the post is older than the default 20 most recent.

The featured post banner disappears on page 2 of the listing

That is the Only on page 1 of the listing option, on by default. Switch it off in the module's Source group to show the banner on every page.

Forms

The form does not appear on the published page

Symptom. The page editor shows an empty form card; the published page shows the headings and contact details but no form.

Cause. The three form modules — Contact details with embedded form, Lead capture hero with embedded form, Newsletter signup band — ship with no form selected, because a form ID belongs to one account.

Fix. Select the module, open the Content tab and pick one of your forms in the Form field. For the blog listing page, do it from Settings → Content → Blog → Templates → Blog listing page → Edit page. See Forms.

The form does not look like the theme

Every embedded form follows the Forms group of the theme settings. If a form looks different, check that Mistral Pro is the active theme (Settings → Content → Themes) and that the page uses a Mistral Pro template.

Video

The hero video does not play

Check, in this order:

No file selected. The theme ships no video. Set Background → Looping video and pick an MP4 from your File Manager in Background video (MP4). See Video.
Motion is off. When Motion and animations is off in the theme settings, or the visitor's browser asks for reduced motion, the hero deliberately shows the poster image instead of the video.
The file is too heavy or not an MP4. Keep the background video under about 3 MB, H.264 MP4, muted and without an audio track (browsers only autoplay muted video).
An image is shown instead. Background is set to Image: the video only plays in Looping video mode.

The showreel card is invisible

Without a showreel video the card is not rendered — that is why it is hidden on a fresh install. Show showreel card is already on in the Display group (check that nobody switched it off); what is missing is the file: open the Showreel card group and set Showreel video (MP4) and a Showreel poster.

Menus, header and footer

The header overlaps the top of my page / text is unreadable over a light hero

The header is transparent over a dark hero by default (Theme settings → Header → Transparent over dark hero sections), and the hero module has Overlap the header on. On a page opening with a light block, either keep the hero's Text tone on dark text with a light solid background, or switch Overlap the header off on the hero, or switch the transparency off globally in the theme settings.

The header's Menu source defaults to Simple menu edited here — the small demo menu stored with the header. Switch it to HubSpot navigation menu and pick the menu you built in Settings → Content → Navigation. The header is global content: the change applies to every page.

Panels are matched by label: Applies to the menu item labeled must be exactly the top-level item's label (same spelling, same case). Only two levels are rendered; a third level is ignored.

The search sends visitors to the wrong page

The header's search box submits to /hs-search-results. If your search results page lives elsewhere, set Search results page path in the header module and in the Search results page's own module.

The language switcher is missing

It is only shown when the page has at least one translation. Check that Show language switcher is on in the header's Display group, and that the page has language variants.

System and membership pages

Each Mistral Pro system template only appears for its own page type in Settings → Content → Pages → System pages: Error 404 and Error 500 for the error pages, Password prompt, Search results, and the three email subscription templates. If none appears at all, the theme is not installed on the account you are looking at.

I cannot assign the membership templates

The four membership templates require Content Hub Professional or above. On lower tiers they exist in the Design Manager but HubSpot offers no place to assign them. See Membership pages.

It ships switched off. Enter your own Google or Facebook app IDs in HubSpot first, then enable them in the social sign-in module on the login page.

Layout and style

A title appears twice

You placed a module that renders its own heading under a Two-tone section heading. Turn off Show section heading in the module's Display group.

A colour I changed on one module no longer follows the theme settings

That is expected: a value set on a module's Style tab overrides the theme setting for that module only. Reset the field to go back to the inherited value.

Shadows do not show on cards

Shadows are off by default (flat design). Turn them on in Theme settings → Layout and spacing → Card and media shadows.

Animations do not play (counters, marquee, orbit, team rotation)

Check Theme settings → Layout and spacing → Motion and animations, then the module's own Behavior switch. The browser's reduced-motion preference also stops them, by design.

An image looks blurry

The uploaded source is smaller than the slot it fills. Upload a source at least as wide as the slot and let HubSpot resize it. See Images and brand marks.

I cannot edit the theme's files

Marketplace themes are read-only so that you keep receiving updates. To change the code, clone the theme (Design Tools → right-click the theme folder → Clone); the clone stops receiving updates. Before cloning, check whether the change is not already a theme setting or a module field.

Still stuck?

See Support — send your account ID, the page URL and a screenshot.