"Error loading the extension!" instead of macros after migrating to Cloud?

[#1]

Posting this because I've seen the question come up here bunch of times, and figured it's worth writing down properly instead of answering it piecemeal in comments.

You migrate to Confluence Cloud, everything looks green in the Migration Assistant, and then someone opens the project dashboard and it's just... red boxes everywhere. Every one says "Error loading the extension!" Naturally the Slack messages start: "is the wiki broken?"

Good news first: Confluence is not broken; your content isn’t gone, but something is definitely missing. It's still sitting in the page's storage format exactly where it was. Cloud just doesn't have anything installed that knows how to read it yet.

Why macros are broken

Old Server or Data Center User Macros and the native HTML macro don't exist on Cloud. When Confluence hits a macro key it doesn't recognize -- html, or whatever custom key your team used -- it can't render it, so it shows the error instead.

There are three common reasons a macro key ends up "unanswered" like this:

1. It's a User Macro. Custom macro created via Confluence admin pannel in browser.

2. It's the HTML macro (or another built-in but deprecated one).

3. It's a 3rd-party app macro that isn't installed on Cloud. Sometimes because there's no Cloud version at all, sometimes because of the clean up on migration.

That's really the whole mechanism. Nothing is corrupted, there's just a missing piece on the Cloud side that used to call the render by macro key.

First: Audit your macros

Before rebuilding anything, figure out which macro keys are actually failing. A handful of recurring keys usually cause the vast majority of errors. Here are 4 places in Data Center to map them out:

Macro Usage statistics

Go to Administration > General Configuration > Macro Usage to see total counts of every macro used across your site, grouped by Atlassian and third-party apps.

User Macros page

Go to Administration > General Configuration > User Macros to inspect custom browser-built macros, their system keys, and Velocity templates.

Universal Plugin Manager (UPM)

Go to Administration > Manage apps, expand an installed app's details, and inspect its enabled modules to find the exact module key of a third-party macro. Key of the module is the same as a macro key.

Search and CQL

Find every page using a specific macro key with CQL (type = page AND macro = "macrokey") or wildcard search parameters (macroName:jira*).

Once you have your inventory of failing keys and target pages, you can choose the best fix for each key.

What fixes macros

It’s not a problem if you have thousands or even hundreds of thousands of affected pages—you don't need to manually edit every page.

When Confluence Cloud loads a page, it looks for an active app or macro registered under the exact macro key referenced in the storage format. The cleanest, non-destructive way to resolve "Error loading the extension!" is to ensure a macro exists on Cloud registered under that same macro key, matching parameters, and expected logic. Once registered, Confluence resolves the key automatically on the next page refresh without requiring page edits.

Broadly, you have two strategic approaches to handle missing macro keys:

1. Preserve the key: Register an app or macro on Cloud under the existing key (via upgraded 3rd-party apps, custom Forge apps, or macro management apps). Parameter's keys also must stay the same to not lost modification data.

2. Modify the storage format: Update or remove the underlying macro tags across affected pages (via manual page edits or programmatic API/database scripts).

Here is how to evaluate which path fits your site.

How to choose your resolution path

Based on your macro audit, evaluate your missing macros through this decision framework:

Upgrade 3rd-party apps to their Cloud equivalents

If a failing macro originates from a Marketplace app, check whether a Cloud version is available. Installing the vendor's Cloud equivalent allows Confluence to map existing macro keys automatically.

If an equivalent doesn't exist—or you choose not to renew the license on Cloud—move to the next options.

Remove low-usage or obsolete macros

If a macro is only used on a few pages and holds no critical data, manually editing those pages to remove the macro tag is the fastest route.

If an obsolete macro is scattered across hundreds of pages, manual editing becomes impractical. In this case, programmatic scripts (via Cloud REST API, migration file updates, or database queries) can bulk-delete the tags or convert their body content into standard text. However, if you need to keep the macro's dynamic functionality active across your site, programmatic removal isn't the answer—you will need to recreate or catch the macro key instead.

Custom Forge app

Building a custom Forge app using the Macro Module is Atlassian's official recommendation for bespoke custom logic. If you have dedicated developer resources and only need to recreate a few critical macros, this is a solid choice.

Just keep the ongoing maintenance in mind: legacy Velocity templates cannot run natively on Cloud, so your macros must be re-implemented from scratch using JavaScript/TypeScript. Additionally, your internal development team will be responsible for maintaining the code, managing deployments, and keeping up with ongoing updates to the Forge platform.

User Macro for Confluence Cloud app

If you need to migrate dozens of custom User Macros without developer overhead, an off-the-shelf Marketplace solution like User Macro for Confluence Cloud bridges the gap. Backed by Atlassian Ventures, it brings familiar Velocity-based templating straight to Cloud, allowing site admins to manage macros directly from the admin panel.

Why it works well for migration teams:

• Familiar Velocity Syntax: Keeps the template logic you already know, avoiding the need to rewrite everything in JavaScript/TypeScript.

• Ready-Made Macro Library: Take advantage of pre-built solutions for legacy staples—such as replacing the deprecated HTML macro—so you don't have to build everything from scratch.

• App Stack Consolidation: Beyond native user macros, simple utility macros from discontinued third-party apps can often be recreated directly in the admin panel, helping streamline your overall Cloud app stack and software budget.

• Dedicated Migration Tools: Offers a bulk Data Center exporter, automated syntax fixing, free vendor migration support, and AI agent for writing custom macros.

• Graceful Macro Sunsetting: Resolves retired or un-migrated app macros cleanly using dummy templates (like Macro to Be Deleted). Instead of breaking layouts with red boxes, it hides the error in view mode and displays an informational banner for page editors.

Wrapping up

Seeing "Error loading the extension!" across a freshly migrated Cloud site can trigger immediate panic, but your content is completely safe—Cloud simply needs something registered to catch those legacy macro keys. By auditing your highest-usage macros first, you can resolve the majority of your broken pages in one go—whether you upgrade third-party apps, prune obsolete macros, build a custom Forge app, or recreate legacy Velocity templates using the User Macro Cloud app.

How is your team handling macro cleanup during your Cloud migration? Are you maintaining custom Forge apps, running storage format scripts, or taking the opportunity to consolidate apps? Share what’s worked (or hasn’t) for you in the comments below!

Disclaimer: I am a CEO at Wombats Corp, the creator of User Macro for Confluence Cloud.