You just finished your migration to Confluence Cloud. You grab your morning coffee, open that one project dashboard your team uses every single day, and your heart sinks. Instead of your beautiful custom charts or navigation buttons, the page is covered in ugly red boxes. Every single one says the same thing: "Error loading the extension!".
Then the Slack messages start coming in. "Hey, why is the wiki broken?" "I can't see the project status!" It feels like a disaster, but here is the thing: your data isn't actually gone. It is still there, tucked away in the page code. Confluence Cloud just doesn't have the "instructions" to read it yet.
Why everything looks broken
This is one of the most predictable headaches in any Confluence migration from Server to Cloud. On your old Server or Data Center setup, you probably had a bunch of User Macros or used the native HTML macro. These were little scripts that did heavy lifting behind the scenes.
The problem is that Confluence Cloud is a completely different system. It doesn't natively support those old custom scripts. When it loads a migrated page and sees a macro key it doesn't recognize—like html or my-custom-button—it just gives up and shows that "Error loading the extension!" message.
Curious how user macros actually disappeared from Cloud in the first place? We dug through old tickets, release notes, and a decade of community threads to get the full story – read it here.
The fix: Re-mapping the keys
So what actually happens is quite simple. You don't need to go through every single page and manually fix them. That would take weeks. Instead, you just need to give Confluence Cloud a "bridge."
You can use the User Macro for Confluence Cloud app to register those missing macro keys. If your old macro was named link-button, you create a new macro in the Cloud app and set the Macro Key to link-button.
The moment you save that key in the app and refresh your broken page, the red boxes disappear. Confluence sees the key, knows where to find the instructions now, and pulls the original data right out of the page storage format. It’s like magic.
If you're still mid-way through your Confluence migration to Cloud and haven't hit this yet, bookmark this page, you probably will.
Making the old macro work in the Cloud
Now, the code you used on Server usually won't work perfectly in the Cloud right away because the "language" (syntax) has changed slightly.
But there is a huge time-saver built in. The app automatically updates your old variables—like changing $paramColour to the new $parameters["Colour"] format that the Cloud requires upon importing macros and right in the template.
What if you have dozens of macros?
If your instance has been around for a decade, you might have 50 or 100 different custom macros. Recreating them one by one sounds like a nightmare.
Turns out, there is a way to handle this in bulk. You can use a tool called the User Macro Exporter on your old Server instance. It bundles all your macros into a single JSON file. You then just import that file directly into the Cloud app. You can even check a box to "Keep original macro key," which ensures everything hooks up perfectly without you having to lift a finger on your migrated pages.
You aren't alone in this
Migration is stressful, and seeing those error messages on day one is the last thing you need. If this is exactly why you're here – an error loading the extension, Confluence pages full of red boxes right after moving to Cloud – the fix really is this simple: match the keys. Do that, and your documentation is back to normal in an afternoon instead of a month.
If you hit a wall or have a really complex script that the converter can't handle, don't sweat it. Reach out to us at info@wombatscorp.com, and we can help you figure out a migration strategy that works for your specific setup.