Udostępnij za pośrednictwem

How to extract and analyze the errors from the hybrid migration report using PowerShell

  • Artykuł

Best practices for making the troubleshooting much easier

 

Before jumping to the report analysis part, please be aware of below recommendations, as these can help you to have a clear picture of the issue and to understand better what should be done next:

  • when the migration fails on the validation phase, you cannot retrieve any migration report, because the move did not actually start, but at least MRS should throw a relevant error message that can be used for troubleshooting.(for example the scenarios where the ExchangeGUID value of the mailuser from EXO does not match the ExchangeGUID from on-prem mailbox).
  • the last migration error is not always very relevant and you might want to see for example what was the first error or the errors generated before the permanent error, as these previous errors can be the root cause for your issue.
  • in some situations the migration errors from TXT report might point for example to some general communication errors or network related errors, but extracting the detailed errors from XML report can provide you more details about the context of the issue.

Exporting and importing the migration XML report from PowerShell

 

When you will start a migration batch from Office 365 EAC, if the migration fails for a particular user, you will download the migration report in TXT format, where you can see some details about the migration, some statistics and the errors encountered .

Sometimes it happens that the migration errors from the TXT report to be very explicit, but in some scenarios these are very general and you are not very sure about how to proceed further.

The good news is that we have at our hand the option to see more details about these failures, by analyzing the migration report from PowerShell and extracting the migration errors in a more detailed and efficient way.

As an admin, you have to follow below steps to export the detailed migration report into an XML file, then you can import it at any future time, to analyze it:

  1. Export the XML moverequest migration report for the affected user from PowerShell connected to Exchange Online:

Get-MoveRequestStatistics <UserName> -IncludeReport -Verbose | Export-CliXml .\move_report.xml

 

  1. Import the XML report into PowerShell variable and "play" with the variable properties afterwards:

  $r=Import-Clixml .\move_report.xml

I consider the method to export the migration report into an XML file being the most efficient option, because during the troubleshooting, you may want to delete the failed move and re-try it, but without saving the XML report, you will loose also the future chance to see the report for previous moves.

 

Analyzing the failures(errors) from the XML report

 

Below command will list all the failures from the report(errors encountered during the migration job):

  $i=0;$r.report.Failures | foreach { $_ | Select-Object @{name="index";expression={$i}},timestamp,failuretype,Message;$i++} | ft

To group all the migration errors based on the failuretype, you can run this command:

  $r.Report.Failures|Group-Object failuretype

 

In order to see the details for a particular failure, you can use failure index from previous command:

  $r.Report.Failures[4]

If you want to see for example the details for the last 2 failures, you can use below command:

  $r.Report.Failures| select -last 2

 

Going further with XML report analysis

 

Another cool thing about XML report is the fact that you can access very easily the report properties. Using below command(of course, after you imported first the XML report into $r variable as describe above), you can list all the properties of the variable $r, that are inherited actually from get-moverequeststatistics:

$r|gm

Futhermore, if you will open and analyze the report from Windows PowerShell ISE, after typing " $r. ", you will get the suggestions list with available properties that you can query for. See example below, where you can display essential information about the move, such as source mailbox size, bag items limit, the move status, etc:

 

The same principle applies to the report section of the $r variable, where using " $r.Report|gm" you can see all the properties that you can access from the move report and some of them can provide very useful  information during the troubleshooting.

 

Why analyzing the XML report and not relying only on the TXT report ? See example below!

 

To understand better why it is more useful to analyze the XML report, in below example I will show you what is the difference between the details we can see in the TXT report, comparing with the XML report, for a particular error:

We can see a lot of  'A corrupted item was encountered: Folder ACL ' errors, which to be honest, are not giving us too much details and we might tend to believe that these are related to some bad/corrupted items.

Now if we export the XML migration report and then import it into $r variable, if we apply above steps, we can see much more details:

From above output we can actually figure out that our error has nothing to do with  corrupted items  and we see the error message  " Failed to find a principal in the target forest that corresponds to a source forest principal.".

If we run $r.Report.Failures[2] , we can see below details:

This message is actually related to some mailbox folder permissions that cannot be migrated, because MRS is also attempting to migrate  folder permissions, along with the mailbox.

In this particular case, I have an on-premises user called nicsi, that was assigned permissions on Calendar folder of the migrated mailbox. We can see more details about this user in DataContext section:

DataContext   : Alias: nicsi; DisplayName: nicsi; MailboxGuid: 93b0a605-5a07-4dce-88b6-724a0ff6c5d9; SID: S-1-5-21-208592880-916065958-2228988610-500; ObjectGuid: 804e7282-271e-42a4-81ae-a48be07522a9;   LegDN: /o=Pronicsi Corp/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=a021023509e84a698ed963ea2060d7ff-nicsi; Proxies: [smtp:nicsi@pronicsi.mail.onmicrosoft.com;   SMTP:nicsi@pronicsi.com];

Then it was easy to understand why MRS was unable to migrate this calendar folder permissions: the mentioned user Nicsi was not in scope of AAD sync, therefore MRS was unable to find any equivalent object in EXO to use it for mapping these folder permissions, generating a "fake" bad item in the report, just to let us know that these permissions could not be migrated.

 

 

Now that you are familiar with the process of analyzing the XML report and extracting the detailed error,  you might want to consult our article about known solutions for hybrid migrations errors, maybe  you can find your migration error documented there:

https://blogs.technet.microsoft.com/exovoice/2017/06/14/hybridmigrationerrors/

Comments