Confluence Server to Cloud Migration: The Technical Guide

Migrating Confluence Server or Data Center to Confluence Cloud is not a one-click operation. Atlassian's native tooling — the Confluence Cloud Migration Assistant (CCMA) — handles the bulk of it, but it has hard throughput limits, silently drops several data types, and lands every migrated page in a legacy editor format that Atlassian is actively deprecating. If you don't plan around these constraints, you'll end up with broken macros, missing content, and a cutover window measured in days instead of hours.

If you are still on Confluence Server, Atlassian ended Server support on February 15, 2024. That makes the migration question less about whether to move and more about how to cut risk while doing it. (atlassian.com)

This guide covers the exact data mapping, the methods available, the hard limits you'll hit, and the edge cases that catch teams off guard. For most teams, the hard work is not exporting data — it is dealing with page tree width and depth, pages with too many Jira macros, pages with too many restrictions or embedded attachments, and nested bodied macros that do not render cleanly in Cloud. Atlassian's own readiness insights flag these structures because they can degrade performance or cause pages to load slowly or fail. (confluence.atlassian.com)

For teams still on Data Center weighing their long-term options, see our Atlassian Data Center End of Life (EOL) 2029 guide. If you're evaluating whether Confluence Cloud is even the right target, our Confluence Alternatives (2026) comparison covers the landscape.

What Actually Migrates (and What Gets Left Behind)

Before choosing a migration method, map your instance by object type. The big mistake is treating all Confluence content as "pages." Permissions, macros, templates, app data, links, and identity objects each migrate under different rules. (support.atlassian.com)

Data That Migrates via CCMA

Data That Does NOT Migrate

This is where teams get burned. Not all data can be migrated with the latest version of the Confluence Cloud Migration Assistant. The following items are silently dropped or require manual recreation:

• Personal drafts — shared drafts migrate, but personal drafts do not
• Custom emojis — must be recreated manually in Cloud
• User avatars — users must re-upload after migration
• Audit logs — server audit logs are not migrated to Cloud
• Analytics data — completely dropped
• Global settings and permissions — must be manually reconfigured
• Application links — must be re-established in Cloud
• Profile information — phone, IM, website, position, department, location fields are lost
• Global PDF stylesheets — dropped
• Activity Stream / 'Recently Updated' view — not migrated
• User-created macros — must be rebuilt as Forge or Connect apps
• Passwords — users must reset unless SSO is configured

For a full breakdown of getting data out of your Server or DC instance before migration, see our Confluence export guide.

Method 1: The Confluence Cloud Migration Assistant (CCMA)

Confluence Cloud Migration Assistant is an Atlassian app created to help with migrations from Server or Data Center to Cloud. Although data migration is its primary functionality, it comes together with a number of assessments and checks that make sure your data can be migrated.

CCMA is the recommended path for most migrations. It's free, maintained by Atlassian, and supports phased pre-migration of users, attachments, and inactive spaces to shrink your cutover window. (support.atlassian.com)

How CCMA Works

1. Install or update the assistant — The Confluence Cloud Migration Assistant is an app available for Confluence Server and Data Center. The Confluence Cloud Migration Assistant is pre-installed in Confluence 6.15 and later. Make sure you're on the latest version.
2. Open the assistant — Navigate to Administration > General Configuration > Migration Assistant.
3. Build a migration plan — When migrating Confluence, you build a migration plan and fill it in with data. You can either include everything in a single plan or divide it into many migration plans.
4. Select spaces — Choose which spaces to include. You won't be able to migrate spaces with space keys that already exist in your Confluence Cloud destination site.
5. Configure user migration — Mark trusted domains. The assistant requires that you mark your domains as trusted or not. We'll migrate only users from your trusted domains.
6. Run pre-migration checks — These validate configuration, email uniqueness, group conflicts, and space key collisions.
7. Run the migration — Monitor progress via the CCMA dashboard.

The 400,000 Pages Per 24 Hours Throughput Limit

This is the constraint that determines your downtime window. The migration assistant's throughput has its limits. The median migration rate (based on all migrations we've observed in the past 3 months) is 400,000 pages per 24 hours. If you try to migrate more pages than that, it's likely that your migration will take longer than 24 hours.

For a 1 million page instance, you're looking at a minimum 2.5-day migration window — assuming no errors or retries. If your estate exceeds 400,000 pages, assume a phased migration unless you're comfortable with a long read-only window.

Reducing Your Cutover Window with Phased Migration

The phased approach is how you turn a multi-day cutover into hours:

• Pre-migrate users and groups first. Atlassian explicitly recommends this. Migrating all users and groups from the directory is faster than trying to bring only a subset tied to selected spaces. If you migrate users separately, it must be all users and groups; subsets are only supported when spaces are migrated at the same time. (support.atlassian.com)
• Pre-migrate attachments in a separate plan. Migrating attachments takes up migration assistant's throughput that could be devoted to spaces and pages. Any sizable chunk of attachments migrated together with spaces will affect the migration speed and, by extension, downtime. Pre-migrating attachments doesn't affect your work around Confluence or block any user actions, so you can add them to a separate migration plan and send to cloud any time before the production migration.
• Pre-migrate inactive spaces. Use the Last edited filter to show only inactive spaces. The exact time depends on how many spaces you want to migrate in a single go. In general, not updated for 24 months is a good choice. Move these weeks before your production cutover.
• Migrate active spaces last, in phases sized to your downtime budget — not your optimism.

CCMA User and Group Edge Cases

Two edge cases matter more than teams expect:

• If you choose the users-related-to-selected-spaces option, only referenced users are brought over, and group-based permissions can disappear if the corresponding Cloud group does not already exist.
• If you re-run group migrations, CCMA does not remove users who were deleted from the source group after the first run. If we find groups with the same name, we will merge the users from the Server group into the Cloud group with the same name. You can continue with your migration without fixing this issue, but it's important to check that this won't cause permission escalation. Audit your Cloud groups before migration.

Plan for partial results too. Atlassian's migration dashboard marks some runs as incomplete, which means some data has already landed in Cloud. If you rerun without cleanup, you're no longer testing from a clean baseline.

Method 2: XML Space Export/Import and Its Limits

The XML export/import method is the manual fallback. You export a space as XML from your Server/DC instance and import it into Confluence Cloud via Administration > Backup and Restore. Atlassian's own pre-migration checklist says to prefer CCMA, and only use the XML path when CCMA cannot be used or when you are importing specific spaces manually. (support.atlassian.com)

The 200 MB Uncompressed XML Limit

This is the hard wall. Site import in Confluence Cloud is restricted to a maximum 200 megabytes for the uncompressed XML files inside the backup zip file. This is the 'data size' of the backup. There's no limit to the size and number of attachments.

The 200 MB limit applies to the entities.xml file inside the zip — not the zip itself. A space with 10,000+ pages and extensive page history can blow past this limit easily. There's no simple way to even approximate how large the file will be, you would have to read every page to see its size and attachments etc.

When customers migrate between large instances, there is a 200MB uncompressed XML limit. For larger customers, even if they break down the backup into space exports, their space exports can exceed that size pretty easily. This is an open issue on Atlassian's tracker with no resolution.

XML Import Prerequisites

Before attempting an XML import into Cloud, validate these requirements:

• Source version: Confluence 6.14.x or later. Earlier versions do not import properly into Cloud. (support.atlassian.com)
• Export type: Confirm exportType=space, not a site export. Cloud space import will fail if you feed it the wrong export type.
• XML validation: Validate entities.xml before you import. Atlassian recommends checking structural integrity with xmllint.
• Space key collisions: The importer does not overwrite an existing space. If the key already exists in Cloud, the import fails.
• Heap: Atlassian recommends at least 4 GB heap for the Data Center side to reduce out-of-memory crashes during the export/import process.

When to Use XML (and When Not To)

Use XML export when:

• Small spaces (under ~5,000 pages with modest history)
• One-off space moves where CCMA isn't an option
• Archival migrations where some data loss is acceptable

Do NOT use XML export when:

• Any space whose entities.xml exceeds 200 MB uncompressed
• Large-scale migrations (use CCMA or a managed service instead)
• You need user mapping and permission preservation

For a deeper dive into export preparation, see How to Export All Data from Confluence.

Confluence Cloud API Rate Limits for Custom Migration Scripts

If you're building custom scripts to migrate content via the Confluence Cloud REST API — for example, to bypass the XML 200 MB limit, handle incremental syncs, or automate macro remediation — you need to understand the rate limiting model.

Confluence Cloud uses a points-based model to measure API usage. Instead of simply counting requests, each API call consumes points based on the work it performs—such as the amount of data returned or the complexity of the operation.

Points-Based Quotas by Tier

Enforcement of the new points-based API rate limits and tiered quota rate limits for Jira and Confluence Cloud apps began on March 2, 2026. The new rate limits apply to all Forge, Connect, and OAuth 2.0 (3LO) apps.

The hourly quotas break down by plan: (developer.atlassian.com)

Points are calculated based on the type of API request and the objects affected. Each request starts with a base cost of 1 point, and additional points are added for each object involved. Not every endpoint costs the same: a simple page fetch or space lookup costs around 2 points, while a user lookup costs 3 points. (developer.atlassian.com)

Hourly quotas are allocated on a per-tenant, per-app basis. Atlassian allocates a separate quota for each tenant to which the app is deployed.

API Token Traffic: A Different Model

This is an important distinction for migration scripts: API token-based traffic is not affected by this change, and will continue to be governed by existing burst rate limits. If your migration scripts use API tokens (Basic Auth), you're still under the older burst-rate model, not the points-based quota. You'll still hit HTTP 429 responses if you exceed burst limits, but the enforcement mechanics are different.

Handling HTTP 429 Errors in Migration Scripts

When you exceed your quota, Confluence Cloud returns HTTP 429 Too Many Requests. Unlike platforms that offer gradual throttling, Confluence Cloud cuts off access entirely until the next rolling window opens. Your script must handle this:

import time
import random
import requests
 
def api_call_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 5))
            # Add jitter to avoid thundering herd
            jitter = random.uniform(0, retry_after * 0.5)
            time.sleep(retry_after + jitter)
            continue
        return response
    raise Exception(f"Rate limited after {max_retries} retries")

Distribute requests over time: Spread your requests evenly throughout the hour rather than sending large spikes at predictable times. Add random jitter to scheduled jobs to avoid thundering herd effects when many apps hit the API simultaneously.

Key requirements for any migration script:

• Automated backoff with jitter — pause execution dynamically when the Retry-After header appears
• Concurrency limits — restrict parallel API calls to avoid burning through the point allocation in the first 10 minutes. Coordinate rate-limit state across threads or workers rather than trying to beat the limit with concurrency.
• State tracking — log every successful page_id creation so the script can resume exactly where it failed after a 429 timeout

A DIY migration script without shared rate-limit state is where operators burn weekends. One worker gets a 429, four others keep hammering, and the whole remediation job stalls. That's fixable, but only if you design for it up front.

Fixing Broken Macros and the Legacy Editor

This is the most time-consuming post-migration issue — and it's getting worse.

The Legacy Editor Is Going Away

Pages migrated from Server or Data Center land in Confluence Cloud in legacy format. In June 2025, Atlassian announced the deprecation of the legacy editor. This will be a phased process beginning in January 2026.

We are announcing the deprecation of the legacy editor in Confluence Cloud, with full deprecation planned for April 2026. As of April 1, 2026, all pages are viewed and edited in the Cloud editor, and unsupported portions may remain viewable but not editable. (support.atlassian.com)

This means every page you migrate will eventually need to be converted to the new Cloud editor — and that conversion is where macros break. Macro triage belongs in pre-cutover planning, not post-migration cleanup. If your migration plan depends on legacy macros just staying legacy, revise it now.

Macros That Break on Conversion

Several macros from Server/DC only work in the legacy editor. Macros listed here are only available in the legacy editor or inside the legacy content macro in the cloud editor. You can still work with the text inside, but the macros can't be moved outside the legacy content macro.

Commonly affected macros:

• {noformat} — legacy editor only
• {panel} — legacy editor only
• {info}, {tip}, {note}, {warning} — legacy editor only
• {section} and {column} — legacy editor only
• {gallery} — legacy editor only
• {content-by-user}, {create-space-button}, {favorite-pages} — legacy editor only

When a page with unsupported macros is converted to the new editor, Atlassian wraps the unconvertible content in a Legacy Content Macro — a read-only container that preserves the content but prevents editing the macro parameters. A "Legacy Content Macro" has been created to help preserve content of unsupported macros in the conversion process.

Separate macro issues into categories for cleanup:

• Still usable but not future-friendly: macros like Panel and Noformat can stay visible after migration, but new instances cannot be inserted in the Cloud editor. Replace them with cloud-native panel and code elements where possible. (support.atlassian.com)
• Depends on vendor support: marketplace macros only migrate well when the app vendor has a cloud migration path. Check the CCMA app assessment before you assume fidelity.
• Needs a new implementation: user-created macros need a cloud app equivalent. Atlassian explicitly calls out recreating them as Forge or Connect apps.

Nested Bodied Macros

The Cloud editor does not support nested macros the way Server or Data Center did. Structures that worked on-premise — like a code block inside a panel — need conversion help or manual restructuring. Even if the content remains visible, it may end up isolated inside the Legacy Content Macro with limits on inline comments, smart links, copy/paste, and collaborative editing. (support.atlassian.com)

Atlassian's readiness insights flag pages with nested bodied macro combinations because some do not render properly in Cloud, and they flag pages with too many Jira issue macros because those pages can become extremely slow or fail to load. (support.atlassian.com)

Fixing Jira Issue Macros

Jira macros embedded in Confluence pages are their own repair job. After migration, you need to re-establish Application Links between your Cloud Jira and Cloud Confluence instances.

Use the Jira macro repair to update any links to Jira. On your Cloud site go to Settings > Jira macro repair and follow the steps.

Jira macros are not handled by general link fixing — they need the dedicated Jira Macro Repair tool. Atlassian also notes exceptions, including Jira macros split across multiple Cloud instances and JQL inside Jira macros. (support.atlassian.com)

Be aware: The Legacy Jira macro will remain unchanged for DC issues, but for Cloud issues it will convert to Jira Work Items (also known as Jira List of Links/SLLV). If your pages heavily use Jira issue/filter macros, expect significant visual and functional changes.

Edge case most teams miss: When Jira links are updated to point to migrated Confluence content, the mapping is based on new Cloud IDs. If you later delete and re-migrate the same Confluence data, those previously updated Jira links cannot simply be retargeted again. Do not run bulk link fixing until you are confident you are done re-migrating the relevant spaces. (support.atlassian.com)

Short Links Break

Confluence short links like https://confluence.example.com/x/PywS may not work after migrating. Replacing them with internal links (or full URLs if they're not in your Confluence site) before migrating should solve this issue. Audit your spaces for short links before migration — find-and-replace in the database is far easier on the Server side than fixing them page-by-page in Cloud.

Application Tunnels for Staged Migrations

If you are running a staged migration where Jira stays on Data Center for a period, Atlassian supports application tunnels for coexistence. Tunnels work with Confluence Cloud paired with Confluence Data Center 7.4+ and Jira Software/Data Center 8.8+. Do not confuse coexistence links with post-migration repair — they solve different problems. (support.atlassian.com)

For teams migrating from other ecosystems and hitting similar macro/web part challenges, see our SharePoint to Confluence Migration guide.

Pre-Migration Checklist

1. Audit and Clean Up

• Remove orphaned content — archive or delete spaces untouched for 24+ months
• Purge old attachment versions — reduces migration time significantly
• Fix user email addresses — All users will need to have a valid and unique email address. If we detect invalid emails or multiple users with the same email, you will get an error. You will need to fix these email addresses before you can run your migration.
• Identify and document custom user macros — these must be rebuilt as Forge/Connect apps
• Export audit logs separately if you need them for compliance
• Flag structurally risky pages — wide page trees, deep nesting, restriction-heavy pages, and pages overloaded with Jira macros or attachments

2. Map Your Marketplace Apps

Not every Server/DC app has a Cloud equivalent. Use the CCMA's app assessment feature to identify:

• Apps with automated migration paths (these migrate via CCMA)
• Apps with Cloud equivalents but no automated migration (manual data transfer)
• Apps with no Cloud equivalent (find alternatives or accept the loss)

3. Run a Trial Migration

Use a staging Cloud site. Verify:

• All spaces imported without space key conflicts
• Page content renders correctly (especially macro-heavy pages)
• Attachments are linked to the correct pages
• Users are mapped to the correct Atlassian accounts
• Jira macros resolve after running the Jira macro repair tool
• Templates function as expected

4. Execute the Phased Production Migration

• Phase 1: Pre-migrate users and groups
• Phase 2: Pre-migrate attachments (runs in the background without downtime)
• Phase 3: Pre-migrate inactive spaces (untouched for 24+ months)
• Phase 4: Final cutover — set Server to read-only, migrate active spaces, run Jira macro repair, verify content, update DNS, decommission Server

5. Post-Migration Validation

• Check for "Former User" attribution
• Re-establish Application Links
• Fix short links
• Re-create custom emojis
• Convert legacy editor pages to the new Cloud editor
• Address unsupported macros wrapped in Legacy Content Macros
• Compare source and destination page and attachment counts on priority spaces
• Test restricted pages with real group memberships
• Open pages with old macros and verify Jira-linked pages still render after repair

Edge Cases That Catch Teams Off Guard

Space shortcuts to other spaces don't survive. If you have space shortcuts pointing to pages in other spaces, they won't appear in Cloud. This is a known issue (MIG-1608).

Draft behavior differs. When migrating a space with the Confluence Cloud Migration Assistant, any edits to existing pages that are saved as drafts are not migrated to the destination Cloud instance. If you create a new page and save it as a draft without publishing it will migrate that draft page over fine. In-progress edits to existing pages are silently lost — only unpublished new pages saved as drafts will come across.

Team Calendar internal subscriptions disappear. If Space A subscribes to Space B's calendar, that subscription is not migrated. Users must re-subscribe manually.

The CCMA can be slow to load with many spaces. If you've many spaces and attachments or you are on Data Center, you might want to break the migration up into a few smaller migrations. The migration assistant can be slow to load and process tasks when there is a lot to manage.

Incomplete migrations leave data in Cloud. If a CCMA run is marked as "incomplete," some data has already landed in Cloud. Rerunning without cleanup means you're no longer testing from a clean baseline.

Choosing Your Migration Method

For most teams with under 400,000 pages, the CCMA with a phased migration strategy works. For larger instances, heavy macro usage, or zero-downtime requirements, you need custom scripts or a managed migration partner.

For more on Cloud-side import capabilities, see our Confluence import guide.

Where ClonePartner Fits

If your Confluence instance is small, lightly customized, and mostly standard pages plus attachments, start with CCMA and a disciplined phased plan. That is the honest answer.

Where teams bring us in is when the migration stops being a transport problem and becomes a remediation problem: large instances that exceed the 400,000 pages/day throughput, spaces that blow past the 200 MB XML limit, heavy macro usage that requires automated conversion rather than manual page-by-page fixes, mixed Jira and Confluence coexistence, or tight downtime windows that don't allow for multi-day cutovers.

Our approach:

• Custom API scripts with intelligent rate-limit handling — automated backoff with jitter that adapts to Atlassian's points-based quota system, with shared state across workers to avoid the 429 walls that crash DIY scripts
• Bypassing the XML 200 MB limit — we migrate large spaces programmatically via the API, eliminating the need to manually split XML exports
• Automated macro mapping and repair — bulk identification and conversion of legacy macros (panel, noformat, section/column) to their Cloud editor equivalents, plus automated Jira macro reference repair
• Continuous delta syncs — instead of a single big-bang cutover, we run incremental syncs that keep your Server and Cloud instances in near-real-time parity until you're ready to switch, minimizing actual downtime to minutes rather than days

We keep the native path when it's good enough, and replace the brittle parts only where the native path breaks.