Skip to content
Yamuno

Documentation

HTML Macro+ for Confluence
Browse

Troubleshooting

Common issues and how to resolve them.

Content Is Not Rendering

Symptoms: The macro shows a blank space or a loading spinner on the Confluence page.

Steps to resolve:

  1. Open the macro editor and check that the HTML tab contains content
  2. Verify the macro was saved (click Save and republish the Confluence page)
  3. Check if the content size exceeds the limit. If so, a size-exceeded error page is shown instead of your content
  4. Try refreshing the Confluence page

External Images Are Not Loading

Symptoms: Images from external URLs show as broken or show the 🔒 blocked placeholder.

Cause: The image's domain is not permitted by the current security settings.

Steps to resolve:

  1. Ask your Confluence admin to open the app's security settings
  2. Check the current security mode:
    • If Block all, no external images can load
    • If Whitelist only, the image's domain needs to be added to the whitelist
  3. Add the domain (e.g. images.example.com) to the whitelist
  4. Save the settings and refresh the page

Embedded iframes Are Blocked

Symptoms: YouTube videos, Google Maps, or other iframes show the 🔒 blocked placeholder.

Steps to resolve:

  1. Ask your admin to whitelist the embed domain in security settings:
    • YouTube: youtube.com or *.youtube.com
    • Google Maps: google.com or *.google.com
    • Other: check the src URL of the iframe and whitelist that domain
  2. Save and refresh

JavaScript Is Not Running

Symptoms: Interactive elements do not work; console errors may appear.

Common causes and fixes:

Cause Fix
External script domain not whitelisted Ask admin to whitelist the CDN domain
Syntax error in JavaScript Check the browser console for errors
Script loaded before DOM is ready Wrap code in document.addEventListener('DOMContentLoaded', ...)
fetch() blocked by CSP Ask admin to whitelist the API domain

Symptoms: Clicking links inside the macro does nothing, or opens the wrong page.

Note: Link navigation inside macros is routed through Confluence's bridge. This is expected behaviour: direct window.open() is intercepted and handed off to Confluence's router.

Steps to resolve:

  1. Ensure the href attribute is set correctly on the link
  2. For external links, use target="_blank" to open in a new tab
  3. For Confluence-internal links, use the full /wiki/... path

"Content Size Exceeded" Error

Symptoms: The macro displays an error page saying the content size limit was exceeded.

Steps to resolve:

  1. Open the editor and reduce the amount of HTML/CSS/JS content
  2. Consider moving large CSS frameworks or libraries to external CDN links (and whitelist the domain) rather than pasting them inline
  3. If the content genuinely needs to be large, ask your admin to increase the content size limit in security settings

"Access Denied" When Opening the Editor

Symptoms: A banner says you do not have permission to access the editor.

Cause: Your admin has enabled Restrict editor access and your account is not on the allowed list.

Steps to resolve:

  1. Contact your Confluence administrator
  2. Ask them to add your account to the allowed users list under Permissions in the app settings

Settings Changes Are Not Reflected in the Preview

Symptoms: You changed the security settings but the preview still shows old behaviour.

Saved settings reach open macros and editors right away. If the preview still looks stale, click the Refresh button in the preview toolbar to re-render it with the current settings.

"Error loading the extension!" on Pages Migrated from Server/DC

Symptoms: After moving from Server or Data Center, some macros show Error loading the extension!.

  • If they were HTML Include, HTML or Macro Toolbox HTML macros, make sure HTML Macro+ is installed and up to date. They then render automatically. See Legacy Server/DC Macros.
  • Other legacy macros belong to other apps, or have no Cloud equivalent, and aren't handled by HTML Macro+.

A Legacy Macro Shows "Unknown macro" or an Error in the Editor

Symptoms: The macro renders fine on the page, but in the editor it shows Unknown macro or Error loading the extension!.

This is expected for legacy macros: Confluence's editor can't open them as they are stored. Open the page in view mode, hover the macro and click Migrate to enable editing. After that it opens in the editor normally.

The Migrate Bar Doesn't Appear on a Legacy Macro

Check that:

  1. You're signed in and allowed to edit the page. Viewers don't see the bar.
  2. You're viewing the page, not editing it.
  3. A site administrator has approved the v6.0.0 app update under Settings → Apps → Manage apps. Migration needs the page-reading permission added in that version.
  4. The macro can be converted. Macros whose body contains Confluence-specific content (page links, images, other macros) are left as they are.

"This page has unpublished changes"

Symptoms: The migrate bar, or the bulk migration preview, says the page has unpublished changes and skips it.

Someone has edits on the page that haven't been published. Their draft still contains the old macro, so migrating now would be undone when they publish. Ask them to publish or discard the draft, then migrate the page again.

HTML Include Says "Content blocked"

The page is on a domain that isn't on your whitelist. Ask a Confluence administrator to add the domain under Security → Domain Whitelisting in the app settings. The blocked address is shown under the message.

"Requires a valid license to work" above a macro, or saving is turned off

Cause: The site has no active HTML Macro+ subscription or trial. Pages still show their content, but the editor can't save and the app's settings show a screen to start the free trial.

Steps to resolve: Ask a Confluence admin to subscribe or start a trial in Confluence → Manage apps. See Licensing.

A {{placeholder}} shows as written on the page

Cause: The library has no variable with that name, so the placeholder is left exactly as written. This is often a typo, or a variable that hasn't been created yet. Placeholders only work in HTML and CSS. In JavaScript, read window.HTMLMacro.vars.name instead.

Steps to resolve: Check the warning in the editor for unknown placeholders, fix the name, or ask a Confluence admin to add the variable under Library → Variables. See Variables.

Still having issues?

Guides for HTML Macro+ for Confluence

Stuck on something this page does not cover? Ask the developers.