Replace an Entra Connect sync server with a staging mode swing migration

To move Microsoft Entra Connect Sync to a new server with no gap in synchronization, install the new server in staging mode with the old server's exported configuration, let it run a full import and full synchronization, and confirm with csexport and CSExportAnalyzer that its pending exports contain only expected changes. Then put the old server into staging mode, take the new server out of staging mode, and confirm that exports run. Because only the server role changes, the existing objects stay joined through the source anchor and nothing is deleted or re-created in Microsoft Entra ID.

Who this is for and what you will have at the end

This guide is for administrators who need to replace an Entra Connect Sync server: an old operating system, a server that hasn't been upgraded in 12 to 18 months, a move to a different datacenter or SQL Server, or a configuration change you want to test away from production. Microsoft calls this a swing migration and recommends it as the safest option when an in-place upgrade can't be rolled back.

At the end you will have:

• A new sync server running the current Entra Connect release with the same configuration as the old one.
• Evidence, in a CSV file, of exactly what the new server would export before it becomes active.
• A clean role switch with only one active server at any time.
• The old server either kept as an up-to-date staging server or fully decommissioned.

Why staging mode makes this zero-downtime

Each server has its own database, so the staging server builds a current picture of both directories while the active server keeps exporting, and it can even sit in a different datacenter. The switch only changes which server writes.

The sync engine doesn't hold state that can't be rebuilt: when the new server imports existing on-premises and cloud objects, it joins them again through the sourceAnchor attribute. What you must carry over is configuration: filtering, optional features and custom synchronization rules.

Prerequisites

Server

• Domain-joined Windows Server with the full GUI; Server Core isn't supported. Microsoft recommends Windows Server 2025 or Windows Server 2022.
• The server is a Tier 0 (control plane) asset. Harden it and restrict administrative access to a tightly controlled group.
• PowerShell execution policy that allows signed scripts; RemoteSigned is recommended during installation.
• TLS 1.2 enabled. From Entra Connect 2.0, installation fails without it.
• .NET Framework 4.7.2 and TLS 1.2, which Microsoft calls out as minimum requirements for the mandatory 2.6 upgrade.

Database and sizing

By default Entra Connect installs SQL Server 2019 Express LocalDB, which has a 10 GB limit, enough for about 100,000 objects. Above that, point the installer at a full SQL Server instance.

All rows list a 1.6 GHz CPU. If you use your own SQL Server: use a case-insensitive (_CI_) collation, one sync engine per SQL instance, don't use Named Pipes, and don't use Azure SQL Database or Azure SQL Managed Instance. Supported high availability options are SQL clustering and Always On availability groups; mirroring isn't supported.

Accounts and versions

• A Microsoft Entra account with Global Administrator or Hybrid Identity Administrator, assigned directly to the user, not through a group. If you want the Connect Health agent active, Microsoft says to install with a Global Administrator; a Hybrid Identity Administrator install leaves the agent disabled.
• Credentials for each on-premises forest (or precreated connector accounts).
• The installer from the Microsoft Entra admin center (Microsoft Entra Connect > Get started). New versions are only published there.
• A target version of 2.6.84.0 or later. Microsoft requires every Connect Sync server to run 2.6.84.0 or later with application-based authentication by 7 April 2027. A new installation is configured for application-based authentication during setup, so a swing migration is also a clean way to meet that requirement.

Step 1: Inventory the current server

On the active server, record the state you need to reproduce and check against later:

Import-Module ADSync
 
Get-ADSyncScheduler                       # StagingModeEnabled, SyncCycleEnabled, interval
Get-ADSyncExportDeletionThreshold -AADUserName "admin@contoso.com"
Get-ADSyncEntraConnectorCredential        # ServiceAccount or Application

Then:

1. Run the wizard and select View or Export Current Configuration. Export the settings to a protected location. The wizard also writes a time-stamped Applied-SynchronizationPolicy-*.JSON file to %ProgramData%\AADConnect every time it changes the configuration, but changes made in PowerShell, the Synchronization Service Manager or the Synchronization Rules Editor are only captured when you export on demand.
2. List optional features in use: password hash sync, password writeback, group writeback, device writeback, Exchange hybrid, directory extensions.
3. Open the Synchronization Rules Editor and list custom rules and any edited out-of-box rules.
4. Note whether this server hosts a Pass-through Authentication agent. The first PTA agent is always installed on the Entra Connect server, so plan to have other agents active before you retire this one.
5. Confirm that accidental-delete protection is enabled. It is on by default with a threshold of 500 deletions.

Step 2: Build the new server in staging mode

1. On the new server, run the installer and stop at the Welcome page.
2. Select Customize, then Import synchronization settings, and browse to the JSON file you exported.
3. On the Install required components page, set anything that isn't imported, such as SQL Server instead of LocalDB or a custom service account.
4. Sign in with your Microsoft Entra account, and provide credentials or connector accounts for each on-premises directory. You can't add or remove directories during an import.
5. On the configuration page, leave staging mode selected (it's enabled by default for imports). Clear start synchronization if you want to run the first cycle manually.

Servers too old to export settings

If the old server predates settings export, run the installer on the new server and stop at the Welcome page, copy MigrateSettings.ps1 from the installer's Tools directory to the old server, and run it there. Copy the entire Exported-ServerConfiguration-* folder to the new server, then select Import synchronization settings and choose MigratedPolicy.json. If the script fails with A positional parameter cannot be found that accepts argument 'True', Microsoft's fix is to edit MigrateSettings.ps1, remove $true, and run it again.

What doesn't come across

Settings import can't be used if the installation includes the Generic SQL or Generic LDAP connector, and it can't be combined with an existing sync database. After the import, reapply these manually:

• Device writeback (cataloged but not applied).
• Restrictions on synced object types or attributes set in the Synchronization Service Manager.
• Custom run profiles and provisioning hierarchy configuration.
• Interactive parameters for AD FS or PingFederate sign-in.

Custom rule precedence must be in the reserved range 0 to 99, or the rule can shift when standard rules are added. Edited out-of-box rules are likely to be placed incorrectly.

Step 3: Copy individual custom sync rules if needed

If you can't use settings import, or a rule was added after your export:

1. On the old server, open the Synchronization Rules Editor, select the custom rule, and select Export. Save the Notepad output as a .ps1 file.
2. On the new server, export any out-of-box rule for the same connected system to find that connector's GUID, which differs between servers.
3. Replace the GUID in the .ps1 file with the new server's GUID and run the script.
4. Repeat for every custom rule.

Also make sure both servers have the same forest connections, domain and OU filtering, and optional features.

Step 4: Run a full import and synchronization

Let the new server catch up before you look at what it would export. In Synchronization Service on the new server, select Connectors and run, in order:

1. Full import on each Active Directory Domain Services connector.
2. Full import on the Microsoft Entra ID connector.
3. Delta Synchronization on each Active Directory connector.
4. Delta Synchronization on the Microsoft Entra ID connector.

If you left the scheduler enabled, it does the same work automatically. Either way, keep the sync cycle running afterwards so the staging server stays current: Microsoft requires a delta sync at least every 7 days, staging servers included, or a full synchronization is needed to recover. Close the installation wizard when you aren't using it, because an open wizard suspends the scheduler.

Step 5: Verify what the new server would export

This is the step that makes the migration safe. The staging server has now calculated every change it would write. Export and review them:

cd /d "%ProgramFiles%\Microsoft Azure AD Sync\bin"
csexport "<Name of Connector>" %temp%\export.xml /f:x
CSExportAnalyzer %temp%\export.xml > %temp%\export.csv

Use the Microsoft Entra ID connector name shown in Synchronization Service; it looks similar to contoso.com – Microsoft Entra ID. Open export.csv in Excel. OMODT is the object modification type and AMODT is the attribute modification type (Add, Update or Delete). To map distinguished names to display names and UPNs, use the csanalyzer.ps1 script from Microsoft's staging server article:

.\csanalyzer.ps1 -xmltoimport %temp%\export.xml

It writes processedbatch1.csv and further batches as needed.

A healthy staging server that matches the active server has few or no pending exports. Investigate anything that isn't explained:

• Deletes usually mean a filtering difference or a missing OU.
• Attribute updates on many objects usually mean a rule is missing, has different precedence, or an optional feature differs.
• Adds of objects that already exist in the cloud mean a join problem.

Fix the configuration, run import and sync again, and repeat until the pending exports are expected. Run the same check against each Active Directory connector if you use Exchange hybrid or other writeback.

Step 6: Switch the active server

Before you switch, confirm:

• The new server's scheduler is enabled and it has synchronized recently.
• If sync rules or scope changed, an initial cycle has run.
• Accidental-delete protection is configured on the new server.
• Pending exports were verified in Step 5.
• The Connect Health agent is up to date.

Put the old server into staging mode

1. On the old (active) server, open the wizard and select Configure staging mode.
2. Sign in with a Hybrid Identity Administrator account.
3. Select the staging mode check box and select Next.
4. Keep the sync process enabled so it continues to stage changes, then select Configure.
5. Confirm:

Get-ADSyncScheduler | Select-Object StagingModeEnabled, SyncCycleEnabled

StagingModeEnabled must be True. If the old server is unreachable, shut it down or isolate it so it can't come back unexpectedly.

Take the new server out of staging mode

At this point both servers are in staging mode and nothing is exporting.

1. On the new server, open the wizard and select Configure staging mode.
2. Sign in, clear the staging mode check box and select Next.
3. Select the option to start synchronization and select Configure.

Don't let two servers be active together even briefly. Microsoft notes that activating a server with password writeback while another server is still active disrupts the older server's service bus communication, because only one active server can use writeback.

Step 7: Verify the new active server

Get-ADSyncScheduler | Select-Object StagingModeEnabled, SyncCycleEnabled, SchedulerSuspended, NextSyncCycleStartTimeInUTC
Get-ADSyncEntraConnectorCredential
Start-ADSyncSyncCycle -PolicyType Delta

Then check:

• In Synchronization Service, the run history shows Export steps completing on the Microsoft Entra ID connector.
• ConnectorIdentityType is Application (application-based authentication), and SchedulerSuspended is False.
• The sync interval is what you expect. The scheduler configuration is stored in Microsoft Entra ID and shared by active and staging servers, except the staging mode flag.
• A test change, such as a new attribute value on a test user, reaches Microsoft Entra ID.
• Password writeback works for a test user if you use it.
• Password hash sync is processing. When staging mode is disabled, PHS resumes from the last watermark and may need a catch-up period. Watch the Application log for events 654 and 656 (batch processing) and 657 (per-user success). Don't restart the sync service during catch-up, or PHS can resume from an earlier watermark.

Step 8: Upgrade or decommission the old server

You now have two choices for the old server:

• Keep it as the staging server. Upgrade it to the same release (or rebuild it) so the pair runs matching versions. Microsoft recommends keeping an active and staging pair on the same version. With only two servers, you have no standby while the second one is being upgraded, which is why some organizations run three or four.
• Decommission it. Uninstall Microsoft Entra Connect and all its components, or delete the virtual machine. A partially removed server that powers on later can still reach Microsoft Entra ID while it can no longer read Active Directory, and overwrite cloud values every cycle.

If the old server used a legacy Sync_ directory synchronization account and the new server uses application-based authentication, remove that account once the old server is gone. For Sync_Server_id@contoso.onmicrosoft.com, the name is Sync_Server_id:

$HACredential = Get-Credential
Remove-ADSyncAADServiceAccount -AADCredential $HACredential -Name Sync_Server_id

Troubleshooting

The new server's first export stops with stopped-deletion-threshold-exceeded. Accidental-delete protection blocked more deletes than the threshold. Event ID 116 in the Application log reports the count. In Synchronization Service, select the Microsoft Entra connector, choose Search Connector Space, set Scope to Pending Export and check Delete. If the deletes are wrong, fix the scope and run Start-ADSyncSyncCycle -PolicyType Initial. Only if every delete is intended, run Disable-ADSyncExportDeletionThreshold -AADUserName "admin@contoso.com", export, and re-enable it with Enable-ADSyncExportDeletionThreshold -DeletionThreshold 500 -AADUserName "admin@contoso.com".

Many attribute updates appear in export.csv. The configuration differs from the active server. Compare the imported JSON with a fresh export from the new server in a text comparison tool, and check custom rule precedence and edited out-of-box rules.

An in-place upgrade of the old server reports "the specified MA could not be found". The Microsoft Entra connector with identifier b891884f-051e-4a83-95af-2544101c9083 doesn't exist (Get-ADSyncConnector -Identifier b891884f-051e-4a83-95af-2544101c9083 returns the same error), and the configuration isn't supported for upgrade. Microsoft's fix is to uninstall and perform a clean installation, which is another reason to rebuild rather than upgrade the old server.

Password writeback breaks on the old server during the switch. Two servers were active with writeback at the same time. Make sure the old server shows StagingModeEnabled True.

Attribute values keep reverting every sync cycle (every 30 minutes by default) after the migration. A forgotten sync server is still active. Find it in Microsoft Entra Connect Health, put it into staging mode, and decommission it fully.

When to consider Cloud Sync instead

Before you build a new Connect Sync server, check whether Microsoft Entra Cloud Sync covers your scenarios. Microsoft now points customers who are upgrading toward that comparison first. The trade-offs are covered in Entra Cloud Sync vs Entra Connect Sync. If the reason for the new server is decommissioning AD FS, plan that separately with the AD FS to cloud authentication migration.

Checklist

• Current configuration exported, optional features and custom rules listed.
• New server sized for the object count, with LocalDB only up to about 100,000 objects.
• New server installed with Import synchronization settings and staging mode on.
• Unimported settings (device writeback, attribute filtering, run profiles) reapplied.
• Full import and synchronization complete; pending exports reviewed in export.csv.
• Old server in staging mode (StagingModeEnabled True) before the new one goes active.
• Exports, writeback, PHS catch-up and application-based authentication verified.
• Old server upgraded as the new staging server, or fully uninstalled.

References

• Microsoft Entra Connect Sync: Operational tasks and considerations (staging mode)
• Microsoft Entra Connect: Upgrade from a previous version
• Import and export Microsoft Entra Connect configuration settings
• Microsoft Entra Connect: Prerequisites and hardware
• Microsoft Entra Connect Sync: Prevent accidental deletes
• Authenticate to Microsoft Entra ID by using application identity
• Migrate from federation to cloud authentication (PTA agent placement)