Troubleshooting IMAP migration to Office 365
This blog is going to be a complete guide on troubleshooting IMAP migration to Office 365 where you learn how to troubleshoot IMAP migration using PowerShell commands.
Table of Contents
Watch the video
Watch this video to learn how IMAP migration to Office 365 works and how to migrate mailbox items to Office 365.
Things to consider before IMAP migration
You can use IMAP migration if your source email system supports IMAP (Internet Message Access Protocol). This particular blog is dedicated to IMAP migration from on-premises Exchange server to Exchange Online. If your source system doesn’t support IMAP, in that case you can consider other migration methods, like, Exchange Hybrid, Cutover or Staged migration.
IMAP migration limitations
Let’s talk about few IMAP migration limitations that we need to be aware of if you are planning for 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.
- By default, the maximum message size that can be migrated is 35 MB. This can be increased up to 150 MB.
- Microsoft’s data migration tool is currently unaware of tools enforcing Messaging Records Management (MRM) or archival policies. Because of this, any messages that are deleted or moved to archive by these policies will result in the migration process flagging these items as missing. Therefore, it is recommended to disable all MRM and archival policies before attempting any data migration to mailboxes.
- You can migrate a maximum of 500,000 items from a user’s mailbox (emails are migrated from newest to oldest).
Supported scenarios in IMAP migration
Let’s discuss few supported scenarios in IMAP migration:
- Migrations from IMAP servers to Office 365 Exchange Online using IMAP4 protocol are supported.
- IMAP migration is not supported between two Office 365 or Microsoft 365 tenants. If your requirement is to migrate mailbox items between 2 Microsoft 365 tenants, consider Cross-Tenant Migration.
- Offboard mailbox migration back to an IMAP server from Exchange Online using IMAP is not supported. Offboarding is only possible using Mailbox Replication Service (MRS) migrations using an MRS Proxy endpoint.
IMAP migration steps
Now let’s talk about IMAP migration steps that will help us to troubleshoot IMAP migration.
Step 1. Verify domain
You need to verify the domain in Microsoft 365 tenant that you want to use for email addresses for the user accounts.
Step 2. Create users and assign licenses
In the second step you need to create user accounts in Microsoft 365 and assign license that has Exchange Online service included so that a mailbox can be provisioned.
Step 3. Create CSV file
In the next step you need to create CSV file and add the users within CSV file that you want to migrate to Microsoft 365.
Step 4. Connect Microsoft 365 tenant with source email server
Next you need to create a Migration Endpoint in Microsoft 365 so that Microsoft 365 tenant can connect with the source email server.
After you create IMAP migration endpoint, run below commands in Exchange Online PowerShell to test the connectivity with source mailbox server:
Test-MigrationServerAvailability -Imap -RemoteServer <Your IMAP server> -Port 993
Test-MigrationServerAvailability -Imap -RemoteServer <Your IMAP server> -Port 143Step 5. Create Migration Batch
In the 5th step you create IMAP migration batch and start the migration.
Step 6. Point MX record to Office 365
Once the migration batch is synced, you will point MX record to Office 365 so that the emails start routing to Exchange Online Protection (EOP)
Step 7. Stop migration batch
Once you verify that the emails are getting routed to Exchange Online Protection, you will complete the migration batch.
Step 8. Send welcome letter to users
And once migration is completed, you can let your users know that now they are using Microsoft 365 as a service.
Troubleshooting IMAP migration to Office 365
When you are troubleshooting IMAP migration to Office 365, you can run below commands to check what is happening in the background like, the status of the migration (if it is failed), items skipped and so on.
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” -IncludeSkippedItems -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_MigUserStats1.xml
Get-SyncRequest -Mailbox “affected user” | Get-SyncRequestStatistics -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_SyncReq.xmlImportant: If you do have a Sync Request created for the user that failed migration, then you should run Get-SyncRequestStatistics command 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.
Based on the failure you got in the SyncRequestStatistics or MigrationUserStatistics commands, 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 a sync request, 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 if it is Failed/Synced or Syncing. If the request is failed, you would then store the Sync Request Statistics into a variable using below PowerShell command:
$syncstats = Get-SyncRequestStatistics [email protected] -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 including their Identity, Name of the Migration Batch user is part of, Status and Last Synced time.
We would then store the Migration User Statistics into a variable or export to XML using below PowerShell commands:
# Store into a variable:
$ustats = Get-MigrationUserStatistics [email protected] -IncludeSkippedItems -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose"
# Export to an .xml file:
Get-MigrationUserStatistics [email protected] -IncludeSkippedItems -IncludeReport -DiagnosticInfo "showtimeslots, showtimeline, verbose" | Export-Clixml C:\temp\EXO_MigUserStats1.xmlCommon IMAP migration errors.
Below you will find few common IMAP migration errors and the steps to troubleshoot them:
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. If you don’t need to migrate these folders, you can exclude the folders from migration also.
Error: TooManyLargeItemsPermanentException has occurred
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. To do this, run below command in Exchange Online PowerShell. To learn more about this error please refer to this link.
Set-Mailbox -Identity [email protected] -MaxReceiveSize 150MBError: Fatal Error TooManyLargeItemsPermanentException has occurred
The error Fatal Error: TooManyLargeItemsPermanentException has occurred suggests that we reached the Large Item limit set on the 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, or on the Sync Request (Set-SyncRequest -LargeItemLimit) so that the migration can be skipped of these large items and migration won’t fail because of this.
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. To troubleshoot this issue, you can try below steps:
Check if you are able to configure IMAP profile in Outlook Desktop for the user. And 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.
- Run Test-MigrationServerAvailability command in EXO PowerShell:
Test-MigrationServerAvailability -Imap -RemoteServer <IMAP server> -Port 993
Test-MigrationServerAvailability -Imap -RemoteServer <IMAP server> -Port 143Error: UserAlreadyBeingMigratedException
If you get UserAlreadyBeingMigratedException error in IMAP migration, follow below steps:
IMAP migrations are done with a Sync Request. Try looking for the existing request with:
Get-SyncRequest -Mailbox “mailbox name” and removing it with Remove-SyncRequest -Identity “mailbox name” and try to migrate the user again.
Conclusion
In this blog we learnt how IMAP migration works and how to troubleshoot IMAP migration process.
You might like our other articles on Cross-Tenant Migration, Exchange Hybrid Mailbox Migration, and Cutover Migration.
If you found this article helpful, please share it within your community and do not forget to share your feedback in the comments below. Please join us on our YouTube channel for the latest videos on Cloud technology and join our Newsletter for the early access of the blogs and updates.
Happy Learning !!