Fix it now
MigrationPermanentException is not one fault. It is the mailbox replication service saying it has classified this failure as one a retry cannot improve, and the actual reason is in the move report rather than in the exception name. Read the report first; resuming before you have it replays the same broken state.
$stats = Get-MoveRequestStatistics -Identity user@contoso.com -IncludeReport
$stats.Report.Failures | Select-Object -Last 5
$stats | Format-List Status,StatusDetail,Message,FailureType,FailureSide
Test-MigrationServerAvailability -Endpoint <endpoint name>
- Read
FailureSidebefore anything else. Source and Target send you to different machines, and most wasted afternoons start by fixing the wrong end. - For a batch-based migration read the same detail with
Get-MigrationUserStatistics -Identity user@contoso.com -IncludeReport | Format-List Status,Error,Report. - If the endpoint test fails, check the proxy on every Exchange Web Services virtual directory the namespace can land on:
Get-WebServicesVirtualDirectory | Format-List Identity,MRSProxyEnabled,ExternalUrl. Turn it on where it is off withSet-WebServicesVirtualDirectory -Identity "SERVER\EWS (Default Web Site)" -MRSProxyEnabled $true. - If the report names a specific mailbox rather than the endpoint, go to the cause blocks below. Microsoft documents four separate faults that all surface under this one exception name.
Do not open by resuming the request. A permanent classification means the same attempt produces the same result, so a resume costs you the time it takes to fail again and tells you nothing new.
If the endpoint tests clean and the report points at one mailbox, the next section explains how MRS decides a failure is permanent and which of the documented causes you are looking at.
Why it happens
A remote move is not a file copy. The mailbox replication service opens an authenticated channel to the other organisation, walks the mailbox item by item, and keeps its own checkpoint while writing into the target. That channel runs over the Exchange Web Services endpoint, through whatever load balancer and firewall sit in front of it, authenticated with the credentials stored on the migration endpoint, and it has to survive for hours.
Every failure gets sorted into one of two buckets. Transient means retrying could plausibly succeed: a dropped socket, a busy store, a timeout. Those are retried automatically and only become a failed request when the retry budget runs out. Permanent means the same attempt will produce the same result, so MRS stops rather than burning the budget. MigrationPermanentException is the label on that second bucket. It is a classification, not a diagnosis.
That is why the exception name tells you so little. The failures Microsoft publishes under it have nothing in common except that none can be retried away: a mailbox GUID never stamped on the on-premises object, a Lync contact list held in Exchange, stale mailbox attributes on the target user, and a move already running somewhere else. Reachability of the source is one more possibility, not the definition.
The ExchangeGUID is not stamped on the on-premises remote mailbox
You have this one if Offboarding a mailbox that was created in Exchange Online, and the report reads “Cannot find a recipient that has mailbox GUID”.
- Read the on-premises value:
Get-RemoteMailbox <alias> | Format-List ExchangeGUID. All zeros means it was never stamped. - In Exchange Online PowerShell, get the real one:
Get-Mailbox <name> | Format-List ExchangeGUID, then stamp it on premises withSet-RemoteMailbox <name> -ExchangeGUID <guid>. - Force a directory synchronisation cycle, then create the move again.
A mailbox created in the cloud does not have this value synchronised back down. Creating mailboxes on premises first and moving them up avoids the whole class of problem.
The target user object already holds a mailbox
You have this one if The message reads “Target user ‘name’ already has a primary mailbox” and the move fails validation rather than part way through.
- On premises, read the attributes:
Get-ADUser -Identity <sam> -Properties homemdb,homemta. - Clear them if they carry values:
Get-ADUser -Identity <sam> -Properties homemdb,homemta | Set-ADObject -Clear homemdb,homemta. - Restart the affected users with
Start-MigrationUser -Identity user@contoso.com.
There is a whole article on this one, because a licence assigned before the move produces the same message from a different direction.
A move is already running for that mailbox
You have this one if “The onboarding move could not be created because user ‘name’ is already being moved”, or UserAlreadyBeingMigratedException.
- Look on both sides:
Get-MoveRequest -Identity user@contoso.comin the Exchange Management Shell and again in Exchange Online PowerShell. - Remove the stale request with
Remove-MoveRequest, or remove the migration user and batch entry if it came from a batch. - If nothing is listed and the error persists, clear the orphaned
msExchMailboxMoveattributes on the on-premises user object, backing up the values first.
The endpoint or its stored credential is wrong
You have this one if Test-MigrationServerAvailability fails immediately and the report names the remote server rather than a mailbox.
- Read what the endpoint stores:
Get-MigrationEndpoint | Format-List Identity,RemoteServer,Username,MaxConcurrentMigrations. - Resolve that name from the machine starting the move and confirm it lands on the published namespace and that the certificate is valid for it.
- Update the stored credential with
Set-MigrationEndpoint -Identity <name> -Credentials (Get-Credential). - If the namespace changed, create a new endpoint and a new batch. A batch holds a reference to the endpoint it was created with.
The transient exceptions in the report never clear
You have this one if CommunicationErrorTransientException repeating against the same mailbox until the retry budget is gone, naming the MRSProxy URL.
- Microsoft’s documented cause is corrupt virtual folders in the Search Folders mailbox. Look for “Search”, “Search Folder” or
IDestinationFolder.SetSearchCriteriain the report. - Have the user close Outlook, then run
outlook.exe /cleanfindersfollowed byoutlook.exe /cleanviewsagainst the mailbox. - If the same exception appears across many mailboxes at once, stop looking at mailboxes and raise a load balancer idle timeout instead.
Full reference
Reading a move report without guessing
| Command | What it gives you |
|---|---|
$stats = Get-MoveRequestStatistics -Identity <user> -IncludeReport |
Loads the request into a variable so the report survives |
$stats.Report.Failures | Select-Object -Last 5 |
The last five failures in sequence, which is where the real error lives |
$stats | Format-List Status,StatusDetail,FailureType,FailureSide |
The summary, read separately so it does not discard the report |
Get-MigrationUserStatistics -Identity <user> -IncludeReport | Format-List Status,Error,Report |
The batch-based equivalent |
Get-MoveRequestStatistics <user> -IncludeReport -DiagnosticInfo Verbose | Export-Clixml <path> |
The form Microsoft asks for when a case is going to support |
Piping -IncludeReport straight into Format-List with a named property list throws the report away, because Report is not one of the properties you named. Assign the result to a variable first.
Endpoint and proxy checks
Test-MigrationServerAvailability -Endpoint <name>tests an endpoint you already have.Test-MigrationServerAvailability -ExchangeRemoteMove -RemoteServer <fqdn> -Credentials (Get-Credential)tests a server you are about to point at.MRSProxyEnableddefaults to$falseon the Exchange Web Services virtual directory, so a rebuilt or freshly added server arrives with the proxy off even though every other server in the array has it on.- Recycle the application pool after enabling it, then retest before you touch anything else.
MaxConcurrentMigrationson the endpoint caps how many mailboxes move at once, andMaxConcurrentIncrementalSyncsmust be less than or equal to it.- TLS-inspecting devices in the path routinely break long-lived authenticated sessions. If the endpoint tests clean from the console but batches die after twenty minutes, that is where to look.
The migration account, without leaving a hole behind
MRS cannot answer an interactive prompt, so a migration account caught by a policy that demands one will fail every time. The wrong answer is to leave a highly privileged account permanently outside multi-factor authentication and conditional access, which is exactly the standing target an attacker looks for. Do it the narrow way instead.
- Create a named conditional access exclusion for that one account rather than removing it from policy scope.
- Scope the exclusion to the public IP addresses the migration actually runs from, so the credential is useless anywhere else.
- Time-box it to the migration window and put the removal date in the change record.
- Remove the exclusion, or disable the account, on the day the batches complete. Do not leave it for the next project.
- Give the account only the administrative role the move requires in the source organisation, and no more.
When the report says nothing useful
- Confirm the source database is mounted:
Get-MailboxDatabase -Status | Format-Table Name,Server,Mounted. - Confirm the mailbox is where the directory says it is:
Get-MailboxStatistics -Identity <user> | Format-List DisplayName,Database,DisconnectReason. - In a multi-site organisation, check that the server that picked up the request can reach the source at all. The work does not always land on the side you expect.
- Reduce concurrency and stagger the largest mailboxes if failures cluster whenever several batches overlap.
- If the source server was decommissioned mid-batch, remove the request and re-create it once the directory has caught up rather than resuming into a gap.
When a licence is the actual fix
Nothing in this article is fixed by a purchase, and no licence repairs an endpoint, a stamped GUID or a stale attribute. Licensing matters at the other end of the same project: every mailbox you land in Microsoft 365 needs a plan that includes Exchange Online, and an unlicensed cloud mailbox only survives a short grace period before the service begins to disable it. That is worth settling before the batches run rather than three weeks after they finish, when the mailboxes start failing for a reason unrelated to anything here. Microsoft 365 Business Standard covers the common case for a smaller organisation, and we can check which plan matches the mailbox sizes, archives and retention rules you are actually moving.
Every code this article covers
| Code | What it points at | Source |
|---|---|---|
MigrationPermanentException |
MRS classified the failure as one a retry cannot fix and stopped work on the request. It is a classification rather than a cause; read the move report for the reason | Microsoft Learn |
MigrationTransientException |
The transient counterpart: MRS expects the operation to be worth retrying and retries it within its own budget | not published by the vendor |
CommunicationErrorTransientException |
The call to the remote MRSProxy endpoint failed. Microsoft’s documented root cause is corrupt virtual folders in the Search Folders mailbox | Microsoft Learn |
ConnectionFailedTransientException |
The connection to the remote endpoint could not be established on that attempt | not published by the vendor |
MapiExceptionNetworkError |
The store connection to the source failed at the MAPI layer | not published by the vendor |
RemoteTransientException |
The remote organisation reported a fault MRS treats as recoverable, commonly throttling or capacity | not published by the vendor |
Confirm the fix worked
Test-MigrationServerAvailability -Endpoint <name>returns a success result.$stats.Report.Failures | Select-Object -Last 5shows the run advancing past the point it previously stopped at.Get-MoveRequest | Group-Object Statusleaves nothing in a failed state.- Target item counts on one completed mailbox are consistent with the source before switchover.
- The conditional access exclusion created for the migration account has been removed, and the change record says who removed it.
Questions people ask about this
Can I just resume rather than investigate?
For a transient exception, yes, and MRS usually does it for you. For a permanent one, resuming replays the same configuration and produces the same failure. The classification is MRS telling you that in advance.
Why does the exception name not tell me the cause?
Because it is a bucket, not a diagnosis. Microsoft documents several unrelated faults that all surface as MigrationPermanentException, so the name only tells you MRS will not retry. The report holds the sequence that led to it and which side reported it.
Does removing an incomplete move request lose data?
It discards the partial target copy, not the source mailbox, which stays intact until the move completes and switches over. Do not remove a request that has already completed.
Should I raise retry limits to push a batch through?
No. Retries absorb genuine noise. If a batch only completes with unusual retry settings, something in the network path is closing connections and it will cause trouble again later, probably during the cutover.
Is exempting the migration account from MFA acceptable?
Only as a named, IP-scoped, time-boxed conditional access exclusion that you remove when the batches finish. A permanent unconditioned exemption on a privileged account is a standing credential-theft target, and it will outlive the project unless the removal is written down.
