During my day to day work as a part of support organization, I work with and help troubleshoot mailbox migrations very often. One type of migrations that we see quite often is IMAP migrations. I wanted to put together an overview of IMAP migration good practices as well as troubleshooting tips related to IMAP migrations. Hopefully, you find this useful! I realize that the second part of the post is a bit dry and might not be relevant unless you actively need to troubleshoot. A few things to get out of the way first:
Here are some considerations that you need to take into the account when you perform an IMAP Migration:
There are 2 ways to perform an IMAP migration to Office 365:
Either method you choose, the IMAP migration needs an IMAP Migration Endpoint created first. Here are some screenshots from Office 365 Exchange Admin Center that show where to locate and create Migration Endpoints: And this is a PowerShell view of an IMAP Endpoint (from get-migrationendpoint) established with remote IMAP server on port 993 and using SSL: If you have issues with creating the IMAP Endpoint, you can use Test-MigrationServerAvailability command while connected to Exchange Online PowerShell to test IMAP connectivity:
Test-MigrationServerAvailability -Imap -RemoteServer <Your IMAP server> -Port 993
Test-MigrationServerAvailability -Imap -RemoteServer <Your IMAP server> -Port 143
When you create the migration batch and specify the Office 365 user mailboxes where you will migrate content via IMAP, the migration service will create Migration Users and corresponding Sync Requests for each user you specified in the CSV File.
Similarly, for Hybrid Remote Moves (Full or Minimal Hybrid Configurations), you would have Move Requests created for the users. This is how you would create the Migration Batch via Exchange Admin Center based on a CSV File where you specify the mailboxes you would migrate to:
You can optionally exclude folders in the IMAP Migration Batch if you don’t want to migrate specific folders, or if you find yourself in scenarios where we have a corrupted IMAP folder. When troubleshooting failed IMAP migrations, Microsoft support will need at least one of the following XML reports from you:
Get-MigrationBatch -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_All_Batches.xml
Get-MigrationBatch <Specific Migration Batch Name> -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_Batch_X.xml
Get-MigrationUserStatistics <affected user SMTP> -IncludeSkippedItems -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_MigUserStats1.xml
Get-SyncRequest -Mailbox <affected user SMTP> | Get-SyncRequestStatistics -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_SyncReq.xml
However, depending on when (in which stage) things have failed, we might not always have a Sync Request for the user or even have a Migration Batch. In that case, you would run commands similar to these:
Get-MigrationEndpoint |FL
Test-MigrationServerAvailability -Endpoint <Identity of the IMAP endpoint from above>
Test-MigrationServerAvailability -Imap -RemoteServer <IMAP server> -Port 993
Test-MigrationServerAvailability -Imap -RemoteServer <IMAP server> -Port 143
Get-MigrationBatch
Get-MigrationUser
Get-SyncRequest -Mailbox <affected user>
If you do have a Sync Request created for the user that failed migration, then you should run Get-SyncRequestStatistics command, as described above, to export the XML report in order to retrieve more information on the cause of the issue. If you don’t have a Sync Request created, but you have a Migration User, you would run Get-MigrationUserStatistics command, as described above. Usually, when customers open support cases with support, for any migration to Office 365, this is because of 2 main reasons:
Based on the failure you got in the Sync Request Statistics or Migration User Statistics, you can find out what is causing the issue and get more details on the migration error. When troubleshooting an IMAP Migration, find out if you have a Sync Request created for the user. If there is one, you would retrieve the Sync Request Statistics for it and store it in a variable or directly export it in an XML report to look at it into detail. To see if the sync request is created for the user, run the following command in Exchange Online PowerShell:
Get-SyncRequest -Mailbox <Affected User SMTP>
Check the STATUS of the Sync Request, is it Failed / Synced / Syncing? Supposing it is Failed, you would then store the Sync Request Statistics into a variable, I used $syncstats in my example below.
$syncstats = Get-SyncRequestStatistics crystal@contoso.com -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose"
We would then look at the failures. Here are some examples of commands to check various failures:
Similarly, if you don’t have a Sync Request but do have a Migration User created and we failed to create a Sync Request, we would need to gather the Migration User Statistics for that user in order to get more details. If you run Get-MigrationUser, you would list all migration users: their Identity, Name of the Migration Batch user is part of, Status and Last Synced time. Example (Get-MigrationUser): We would then store the Migration User Statistics into a variable or export to XML.
# Store into a variable:
$ustats = Get-MigrationUserStatistics crystal@contoso.com -IncludeSkippedItems -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose"
# Export to an .xml file:
Get-MigrationUserStatistics crystal@contoso.com -IncludeSkippedItems -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_MigUserStats1.xml
Next, we would use similar commands as we did to retrieve failures and internal failures from Sync Request Statistics. For example, to retrieve Last Failure from a Migration User Statistics, you would run a command similar to this: $ustats.Report.Failures[-1] Note that for troubleshooting IMAP failures, we prefer Sync Request Statistics instead of Migration User Statistics (if we have a Sync Request in place for the user). Next up, I have gathered some of more common (that we see in support) IMAP Migration Errors / Failures and what you can do to fix them.
Message : Imap server sent NO response to SelectCommand. Response code: '', message: 'Invalid mailbox name: Junk/'.
Message : Imap server sent NO response to SelectCommand. Response code: '', message: 'Invalid mailbox name: Sent/'.
This can be because we have invalid folder names with Forward Slash Characters. Reference here. If you don’t need to migrate these folders, you can exclude the folders from migration also.
Error: Mailbox folder hierarchy contains multiple roots: [Folder1: EntryID: [len=54, data=563D313B503D494D41503B46503D37393145423136314534463244383234433438443433413634463936393641354444333942383235], ParentID: [len=54, data=563D313B503D494D41503B46503D33304134424342304331383135314645423643353933414244423837374630393933413432393135], Type: Generic], [Folder2: EntryID: [len=54,
The "duplicate root" parent folder is the "SomeHiddenFolder" that is not returned by IMAP LIST command. So, when MRS runs LIST to enumerate folder hierarchy, it gets something like this: Inbox SentItems TopLevelFolder TopLevelFolder/NormalSubfolder SomeHiddenFolder/ Folder1 SomeHiddenFolder/ Folder2 Note that SomeHiddenFolder is *not* returned as a separate entry in the LIST command output. You would look in report.Failures to see the Folder Names impacted. In this example, it is Folder1 and Folder2. You would check the Folder Hierarchy of the affected user by this error, paying attention to folder names and their parent folder. Problem can also be duplicated folder names or parent folder to be a Public / Shared Folder (for those raising eyebrows right about now – access to public folders through IMAP was a thing in legacy versions of Exchange, for example Exchange 2003). You can also run the following script to LIST IMAP Folders for that mailbox: Get-ImapFolders.ps1 from GitHub and send us the output to see the IMAP Folders List together with the Sync Request Statistics XML. Another thing you can do is run Remote Connectivity Analyzer for IMAP test and select Exchange Server Tab (even if source IMAP server is not an Exchange server) and then IMAP Email under INTERNET Email Tests, fill in the affected user settings and then SAVE report as HTML and send us the file in order to see the IMAP Folders list. Ultimately, our support can’t do much for you in this situation other than identifying problematic folders. It is up to you to make the Folder "SomeHiddenFolder” a SELECTABLE folder and if needed, discuss with your vendor where original data is located. You could also try to create a new folder, selectable in IMAP and move the content from "SomeHiddenFolder” to this New Folder, including its subfolders, example Folder1 and Folder2.
As per our current documentation, the message size limit that we can move to Office 365 Exchange Online during an IMAP Migration is maximum 35MB. However, for IMAP migrations, where we need to have mailboxes created in Office 365 before we can migrate with IMAP, we can increase the message size limit up to 150MB on the target mailbox and this will allow email messages up to 150 MB size to be moved to Office 365 during IMAP Migrations.
Set-Mailbox -Identity alias@domain.com -MaxReceiveSize 150MB
This setting will also allow the user to receive larger email messages via transport (if the sender is capable). We don’t recommend lowering this limit back to 35 MB if you already migrated emails larger than 35MB. The Error "Fatal Error TooManyLargeItemsPermanentException has occurred." suggests that we reached the Large Item limit set on migration batch. Usually large item limit is set to 0 and if we encountered at least 1 email message in the source mailbox bigger than 35MB (default MaxReceieveSize on the Office 365 Mailbox), the limit would have been reached and migration is failed for that user. So you need to either Increase MaxReceiveSize (maximum 150MB) on the affected O365 User Mailbox to be able to migrate email messages larger than 35MB or increase the LargeItemLimit on the migration batch from GUI or from PowerShell with set-migrationbatch -LargeItemLimit XX or on the Sync Request (Set-SyncRequest -LargeItemLimit XX) so that we can skip migration of these large items and migration won’t fail because of this.
MigrationPermanentException: Unable to log into account. --> Unable to log into account. --> The username or password for this account is incorrect, or IMAP access is disabled. --> Imap server sent NO response to LoginCommand. Response code: '', message: 'LOGIN failed.'.
This error suggests bad login (wrong username or password) or that IMAP protocol is disabled. If more or all users are affected, there might be issues with IMAP server certificate. Suggestions for this issue: 1) Check if you are able to configure IMAP profile in Outlook Desktop for the user 2) Check if you are able to connect to the IMAP Source Mailbox and List folders with one of these 2 methods:
3) Test-MigrationServerAvailability command in EXO PowerShell
Test-MigrationServerAvailability -Imap -RemoteServer <IMAP server> -Port 993
Test-MigrationServerAvailability -Imap -RemoteServer <IMAP server> -Port 143
4) If you use a Super User / Admin password, make sure the CSV file is created properly. See this and this. 5) If the source server is Gmail, this error message might happen because 2 step verification process/ app password which is required when migrating from it.
For example, we might get a Permanent Failure after these transient failures which would make migration to fail for a specific user or more.
MigrationMRSPermanentException: Error: The job encountered too many transient failures (61) and is quitting. The most common failure is ImapCouldNotParseResponseException/ImapUnexpectedTokenFormatException with the hit count 57. --> Imap server sent a response that we could not understand. Command: 'WIR01992 UID FETCH 16967 (INTERNALDATE UID BODY.PEEK[]) '. Response: '' >>''. --> Unexpected response format - expected ')', actual ' '.
This error suggests that the IMAP server returned a bad response format, it was expected a parenthesis after Date / Time of the messages received. In this situation, you would need to discuss with vendor where at the mailbox source to help you fix this issue.
Message : Imap server reported an error during SelectCommand indicating that it encountered some bug: 'Internal error occurred. Refer to server log for more information. [2018-11-29 10:40:44] (0.002 + 0.000 + 0.001 secs).'.
DataContext : --------
Operation: ImapMailbox->GetFolderInternal<T>() for folder < >
The error message is generated at the selection of one or maybe more folders on the Source IMAP server (SELECT command) and according to the failure, the admin should check the logs that are generated on that IMAP server around the timestamp of the failure. To retrieve the Last Failure or the previous one before last, you can use the commands below:
$syncstats = Get-SyncRequestStatistics user@domain.com -IncludeReport
$syncstats.Report.Failures[-1]
$syncstats.Report.Failures[-2]
You can use one of these 2 methods below to LIST the Source IMAP Folders for the user and see their names:
If the folder referenced in the error is found in the Sync Request Failure, you can try to Exclude it from IMAP migration batch when retrying migration. Many thanks to all that contributed to this blog post: Nino Bilic, Brad Hughes and Cristian Dimofte.
Mirela Buruiana
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.