How to Migrate User Macros from Server to Cloud

{"timestamp":1792799572928,"msg":"A unknown Exception Occurred","errorMsg":"The provided AtlassianHostUser did not specify a user to act as.","code":"500"}

Why Migrate User Macros to Confluence Cloud?

Migrating to Confluence Cloud is a complex process, and one of the biggest challenges is macro migration. If a macro is not migrated properly, pages will display errors such as:

"Error loading the extension!" or "Unknown macro: macro key"

This results in broken pages across your Confluence instance, leading to poor user experience and lost functionality.

Good News: User Macros CAN be migrated to Cloud!

Yes, it’s possible to migrate User Macros from Confluence Server and Data Center to Confluence Cloud using the right approach.

Key Requirements for Migration

For a macro to function correctly after migration:
✅ The Cloud instance must have the same macro registered with the same unique identifier (macro key).
✅ The macro parameters must match (if applicable).
✅ Confluence Cloud will automatically pick up migrated data from the Confluence Storage Format and render the macros properly.

User Macro Exporter

Take a look at our User Macro Exporter App that can help you to migrate your User Macros from Confluence Server and Data Center to Confluence Cloud.

Step-by-Step Migration Process (Example: "Link Button" Macro)

Let's go through the migration process with a real example of a User Macro.

Step 1: Create the Macro in Server/DC

Here’s an example of a "Link Button" user macro in Confluence Server or Data Center.
It shows a rounded button with clickable text colored into one of three predefined colors.

Macro Details:

Macro Name: link-button
Macro Title: Link Button

Macro Template:

## @param text:title=Button text|type=string|required=true|desc=Your name
## @param url:title=URL|type=string|desc=Insert the link e.g. https://wombatscorp.com
## @param color:title=Button Color|type=enum|enumValues=Mocha Mousse,Peach Fuzz,Viva Magenta|default=Mocha Mousse|desc=Choose your favourite colour

#set($color = "#A47864") ## default Mocha Mousse color
#if ($paramcolor=="Peach Fuzz")
  #set($color = "#FFC196")
#elseif($paramcolor=="Viva Magenta")
  #set($color = "#BB2649")
#end

<style> .custom-button { --aui-btn-bg: $color; } </style>

<button class="aui-button custom-button">
  <a href="$paramurl">$paramtext</a>
</button>

Let’s add the macro to page and set parameters:

Step 2: Migrate the Page to Cloud

Now, let’s assume the following Confluence page exists on your Server/DC instance

Storage format of the page is the following. We will migrate it as is to the Cloud

<p>Please click this <strong>Peach Fuzz</strong> color button</p>
<p><ac:structured-macro ac:name="link-button" ac:schema-version="1" ac:macro-id="f1eb0e51-45f5-4f52-b749-5a318d6b5db7">
  <ac:parameter ac:name="color">Peach Fuzz</ac:parameter>
  <ac:parameter ac:name="text">Text</ac:parameter>
  <ac:parameter ac:name="url">https://wombatscorp.com</ac:parameter>
</ac:structured-macro></p>

After migrating to Confluence Cloud, the page will not display the macro but instead show:

"Error loading the extension!"

Step 3: Create the Same Macro in Cloud

{"timestamp":1792799572932,"msg":"A unknown Exception Occurred","errorMsg":"The provided AtlassianHostUser did not specify a user to act as.","code":"500"}

More detailed instructions for macro creation are here Step-by-Step: User macro creation

Important: Keep the Macro Key the Same!

When creating the macro in Cloud, ensure that:
Key: link-button (must match exactly original Macro Name)

Cool Feature: Parameter Conversion

After copying the original Velocity template into User Macro for Confluence Cloud, a Convert & Save button will appear.

By clicking it, the parameters will be automatically updated:

Before Conversion:

@param Colour ($paramColour)
@param Size ($paramSize)

After Conversion:

$parameters["Colour"]
$parameters["Size"

This ensures that your macro follows the correct Confluence Cloud parameter format.

Screen Recording 2026-05-05 at 15.52.26.gif

Step 4: Success!🎉

Now, reload the migrated page in Confluence Cloud.

✅ The "Link Button" macro is now recognized and rendered correctly.
✅ The original parameter values (Colour, Size) remain intact.
✅ The migrated content appears exactly as it did in Server/DC—no more "Error loading the extension!" errors!

Macro has been migrated and kept the data.

Need Help with Migration?

We understand that every company has unique macros that may require custom migration strategies.

💬 Get expert assistance!
📅 Schedule an appointment with our team, and we’ll help you migrate your macros efficiently, ensuring a smooth transition to Confluence Cloud.