Hybrid migration endpoint "could not be completed": fixing MRSProxy and 401 errors

Before Exchange Online can move a single mailbox in a hybrid deployment, it has to reach the MRSProxy service on your on-premises Exchange servers. When it can't, the Hybrid Configuration Wizard, Test-MigrationServerAvailability or a new migration batch stops with a long, generic-looking error. In this post I'll show you how to read that error, which layer it points to (MRSProxy settings, credentials, publishing, certificates or the Hybrid Agent) and how to prove the endpoint works before you schedule real moves.

Symptoms#

You hit the problem in one of three places:

• The Migration page of the Exchange admin center won't create the migration endpoint or start a remote move batch.
• Test-MigrationServerAvailability, run in Exchange Online PowerShell, returns Result : Failed.
• The HCW fails while it validates the migration endpoint or the Hybrid Agent.

The first line of the message is usually generic; the cause is in the error details that follow it:

The connection to the server 'mail.contoso.com' could not be completed.

The Mailbox Replication Service was unable to connect to the remote server using the
credentials provided. Please check the credentials and try again. The call to
'https://mail.contoso.com/EWS/mrsproxy.svc' failed. Error details: The HTTP request is
unauthorized with client authentication scheme 'Negotiate'. The authentication header
received from the server was 'NTLM,Negotiate'. --> The remote server returned an error:
(401) Unauthorized.

The call to 'https://mail.contoso.com/EWS/mrsproxy.svc' timed out.

In modern hybrid the server name isn't your own host name but a GUID under resource.mailboxmigration.his.msappproxy.net: that's the Hybrid Agent's address.

Why it happens#

A remote move is driven by the Mailbox Replication Service (MRS) in Exchange Online. It connects to https://<your EWS host>/EWS/mrsproxy.svc, a service inside the EWS virtual directory that is off until you (or the HCW) enable it. Every layer between Exchange Online and that service has to work:

How to fix it#

1. Reproduce the error in Exchange Online PowerShell#

Test exactly what your batches use: take the RemoteServer value of the existing endpoint.

Connect-ExchangeOnline -UserPrincipalName admin@contoso.com
Get-MigrationEndpoint | Format-List Identity, EndpointType, RemoteServer

$cred = Get-Credential CONTOSO\svc-migration
Test-MigrationServerAvailability -ExchangeRemoteMove -RemoteServer mail.contoso.com -Credentials $cred |
  Format-List Result, Message, ErrorDetail

2. Enable MRSProxy and WS-Security on every server#

In the Exchange Management Shell on-premises:

Get-WebServicesVirtualDirectory -ADPropertiesOnly |
  Format-Table Server, MRSProxyEnabled, WSSecurityAuthentication, ExternalUrl -AutoSize

Set-WebServicesVirtualDirectory -Identity "EX01\EWS (Default Web Site)" -MRSProxyEnabled $true -WSSecurityAuthentication $true

Repeat for every server that can answer the endpoint's host name, not just the one you picked in the HCW. In the on-premises EAC the same switch is Servers › Virtual directories › EWS › Edit › General › Enable MRS Proxy endpoint.

3. Fix the credentials#

• Enter the account as CONTOSO\svc-migration, not as a UPN; Microsoft's hybrid migration troubleshooter calls this out specifically.
• Use an on-premises account that can move mailboxes, such as a member of Organization Management or Recipient Management, and check it isn't locked out or expired.
• If the password changed after the endpoint was created, update the endpoint instead of recreating it:

Set-MigrationEndpoint -Identity "<endpoint name>" -Credentials (Get-Credential CONTOSO\svc-migration)

A 401 that survives a known-good password usually means something other than Exchange is answering, or a load balancer is offloading TLS while Extended Protection is enabled, which isn't supported. See Extended Protection on Exchange Server.

4. Publish EWS without pre-authentication#

Microsoft's troubleshooter lists the paths that must reach Exchange without being authenticated at a perimeter device: /ews/mrsproxy.svc, /ews/exchange.asmx/wssecurity, /autodiscover/autodiscover.svc/wssecurity and /autodiscover/autodiscover.svc. Allow the Exchange Online ranges from "Microsoft 365 URLs and IP address ranges" on 443, and exempt them from intrusion detection flood limits, because a big batch can look like an attack. A quick check from an outside machine:

curl.exe -s -i https://mail.contoso.com/EWS/mrsproxy.svc

Good: HTTP/1.1 401 with WWW-Authenticate headers offering Negotiate and NTLM, which is IIS on Exchange asking for credentials. Bad: a redirect or an HTML sign-in page (pre-authentication), a timeout (firewall) or a certificate error.

5. Check the certificate#

The certificate on the published name must come from a public CA, be in date and include the endpoint FQDN, on the Exchange servers and on any load balancer or reverse proxy that terminates TLS:

Get-ExchangeCertificate | Where-Object { $_.Services -match 'IIS' } |
  Format-List Subject, CertificateDomains, NotAfter, Thumbprint

After a renewal, follow renewing the SAN certificate so IIS and every device in front of it present the new one.

6. Modern hybrid: check the Hybrid Agent#

If RemoteServer ends in msappproxy.net, MRS traffic goes through the Hybrid Agent. Timeouts there usually mean the agent service is stopped, its outbound connectivity is blocked, or it can't reach the Exchange server it publishes. Work through the Hybrid Agent troubleshooting steps, then rerun the HCW so it validates the endpoint again.

7. Clear stale requests and get a sharper error#

An old move request for the same user can block a new one. In Exchange Online PowerShell, check with Get-MoveRequest and remove completed or failed leftovers with Remove-MoveRequest. If the batch wizard still returns something vague, a single move from PowerShell often gives a more precise error:

New-MoveRequest -Identity 'user@contoso.com' -Remote -RemoteHostName 'mail.contoso.com' `
  -RemoteCredential $cred -TargetDeliveryDomain 'contoso.mail.onmicrosoft.com'

Verify the fix#

• Test-MigrationServerAvailability returns Result : Success against the endpoint's RemoteServer.
• A one-mailbox test batch starts and its move request makes progress:

Get-MoveRequest -Identity 'user@contoso.com' | Get-MoveRequestStatistics |
  Format-List Status, StatusDetail, PercentComplete

Good looks like a rising PercentComplete and, for a batch you complete manually, the batch showing as synced. If the endpoint is healthy but individual moves fail, continue with hybrid mailbox migration batch errors.

Prevent it next time#

• Run Test-MigrationServerAvailability after every certificate renewal, firewall or reverse proxy change, password change and Extended Protection rollout.
• Add "MRSProxy and WS-Security enabled" to your build checklist for new Exchange servers.
• Use a dedicated migration account, and update the endpoint whenever its password changes.
• The same endpoint serves public folder moves: see migrating public folders to Exchange Online.

References#

• Enable the MRS Proxy endpoint for remote moves (Microsoft Learn)
• Troubleshoot migration issues in Exchange hybrid (Microsoft Learn)
• Test-MigrationServerAvailability (Microsoft Learn)