Confluence Macro Troubleshooting

User macros can occasionally encounter issues, leading to unexpected behavior or error messages. These errors can arise from a variety of causes, such as changes to the macro configuration, syntax errors, or platform-specific constraints. Below are common scenarios where Confluence macros are not working, or when you are faced with a Confluence broken macro error.

🛑 Error Message / Situation	🐛 Common Symptoms	⚙️ Causes	🛠️ Resolution
“Error loading the extension!” or “Unknown macro: macro key”	A Confluence broken macro message is displayed. Macro content fails to render.	Macro does not exist on the instance. Macro was deleted or disabled in the admin panel. Imported pages include unsupported macros.	Re-enable or recreate the macro in the admin panel. Ensure the macro is supported on the platform.
“App is not responding. Wait or cancel?”	The macro does not load. Confluence UI hangs.	App providing the macro is experiencing downtime or connectivity issues.	Check the app’s status on the Atlassian Marketplace. Contact the marketplace partner if the issue persists.
Syntax Errors	Macro fails to render properly. Error messages referencing invalid code.	Syntax error in the macro template. Macro saved with code issues.	Review and fix errors in the macro template. Test the macro in a sandbox before deploying.
“License has not been renewed. Macro creation functionality is disabled.”	Macro fails to load. Error messages referencing license issues.	License for the app or macro provider has expired.	Renew or activate the license through the Atlassian license and order portal.
Macro Not Available in Macro Browser Immediately	Macro does not appear in the browser list after creation.	Confluence requires a refresh to register the new macro.	Reload the Confluence page to make the macro visible by pressing Ctrl + R (Windows) or Command + R (Mac).
Macro Hidden Due to Visibility Toggle During Creation	Macro not showing in macro browser. Cannot find macro using slash (/) shortcut.	Visibility for the macro was set to hidden during creation.	Update the macro’s settings in the admin panel to make it visible.
“Broken Link” in static content macros using Storage Format	Macro fails to render. Relevant error message.	Invalid XHTM-based syntax (error thrown by Confluence).	Review and fix errors in the macro template.
“Something went wrong. User did not have access to specified resource(s). Refresh app“	Macro fails to render. Relevant error message.	In most cases, error occurs when a Confluence built-in macro is placed inside a rich-text user macro, losing its outer context.	Remove the macro from the body.