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:
- We support migrations from IMAP servers to Office 365 Exchange Online using IMAP4 protocol.
- We don’t support IMAP migrations between two Office 365 tenants. Our documentation for this scenario can be found here.
- We also don’t support offboarding back to an IMAP server from Exchange Online using IMAP. Offboarding is only possible using Mailbox Replication Service (MRS) migrations using an MRSProxy endpoint.
- We don’t recommend IMAP migrations from Exchange on-premises servers. In such scenarios, we recommend using a native migration method (Cutover or Minimal / Express Hybrid). We also don’t recommend Staged migration from Exchange 2007 or Exchange 2003 servers if you intend to keep directory synchronization in place after mailbox migration to Office 365. The recommended migration method when migrating from these old Exchange Servers when Directory Synchronization is required for your organization is Minimal Hybrid Configuration; this requires inserting an Exchange 2010 (for Exchange 2003 servers) or Exchange 2013 (for Exchange 2007 servers) and running Minimal HCW. This will give you a free Hybrid license and will allow you to perform an MRS migration (this means there is no need to recreate Outlook profiles). The Minimal HCW will also allow you to be in a supported scenario when you have Exchange Online Mailboxes and the AD users synced to Azure AD and you will need to manage your Office 365 Mailboxes using on-premises Exchange 2010 / Exchange 2013 Management tools (Exchange Admin Center and Exchange Management Shell). This is due to directory synchronization which requires administration of Exchange Online Mail Attributes from on-premises Exchange for your synced users. Managing Exchange Online Mailboxes from Exchange 2007 or Exchange 2003 servers after mailbox migration is not supported. More about Minimal and Express Migrations can be found here.
Here are some considerations that you need to take into the account when you perform an IMAP Migration:
- Only items in a user's inbox or other mail folders can be migrated. You can't migrate contacts, calendar items, or tasks. (Note that we are working on a richer migration experience for G Suite to Exchange Online migrations, as mentioned here.)
- By default, the maximum message size that can be migrated is 35 MB. This can be increased up to 150 MB.
There are 2 ways to perform an IMAP migration to Office 365:
- Using a graphical user interface: either Exchange Admin Center or Office 365 Admin Center
- Using PowerShell
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:
- Migration failed, and they are unable to migrate one or more users to Office 365. Errors break down in two categories:
- Permanent – the error that actually made the migration fail
- Transient – errors which might slow down the migration to the point where it might fail at the end
- Migration is slow or stalled due to Office 365 Resource Throttling or IMAP Server performance issues. These depend on many factors like source server performance and network related configurations, capabilities or issues. More info here. It can also happen that Office 365 will stall the migrations to protect Office 365 Servers health and also because migrations have a lower priority assigned than things like mail-flow tasks or client connectivity. More info on that can be found here.
Errors are our friends – how to troubleshoot in practice
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:
- Retrieve Last Failure: $syncstats.Report.Failures[-1]
- Retrieve the Last 2 Failures: $syncstats.Report.Failures | select -Last 2
- Retrieve First Failure: $syncstats.Report.Failures[0]
- Count all failures and group them by failure type: $syncstats.Report.Failures | group failuretype | ft -autosize
- List all the failures with their details: $syncstats.Report.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.
1. Error: Imap server sent NO response to SelectCommand
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.
2. Error: Mailbox folder hierarchy contains multiple roots: FolderHierarchyContainsMultipleRootsTransientException
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.
3. Error TooManyLargeItemsPermanentException has occurred
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.
4. Error: Imap server sent NO response to LoginCommand. Response code: '', message: 'LOGIN failed.'.
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:
- Run Get-ImapFolders.ps1 Script from GitHub
- Go to 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 as mentioned in the CSV file you used for Migration Batch and see if you are able to connect
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.
5. Errors that suggest RFC non-compliant source IMAP Servers.
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.
6. Errors that suggest Source IMAP Server Bugs or Internal Errors
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:
- Run Get-ImapFolders.ps1 Script from GitHub
- Go to 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 IMAP User Details and check the LIST of folders.
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.