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.

Steps to resolve:

  1. Click the Refresh button in the preview toolbar — this bypasses the settings cache and fetches the latest settings
  2. If the preview still shows stale behaviour, wait up to 30 seconds for the cache to expire and click Refresh again

Still Having Issues?