Troubleshoot the new data migration service

Here’s how to fix problems you might have when setting up and migrating data with the new data migration service.

• Troubleshoot migrations from Google Workspace
• Troubleshoot migrations from an IMAP server
• General troubleshooting help

Troubleshoot migrations from Google Workspace

If you have issues migrating email data from Google Workspace, start with these steps.

1. Check the email address of the super admin

Make sure you entered a correct and valid email address of a source domain Google Workspace super administrator.

If you get an error when trying to access the authorization request, the email has been sent to someone who isn't a super administrator on the source domain. To fix the issue, in your Google Admin console on the target domain, click Disconnect and create a new connection using a valid super administrator email address for the source account. For details, go to Request authorization.

2. Verify that the super admin has given consent

If you are a super administrator on the source account, to verify whether you gave consent to the authorization:

1. Go to the domain-wide delegation settings in the source account.
2. Check whether Data Migration (New) is listed as a client.

   For more details about domain-wide delegation, go to Control API access with domain-wide delegation.

3. If it isn't listed as a client, authorize by clicking the consent link sent in the authorization request email.

3. Check that the email link is valid

The authorization consent link expires after 24 hours. If the super admin on the source account doesn't grant consent within that time frame, click Resend email to send a refreshed link to them. 

Troubleshoot migrations from an IMAP server

1. Check the connectivity to the IMAP server

• Ensure that the IMAP server is hosted on port 993 and connects to the Google IP address ranges.
• Verify that the IMAP server uses IMAP over SSL (IMAPS).

2. Check the credentials of the users

Make sure that you entered the correct username and password of the source users. If you're migrating from an IMAP server that authenticates using app passwords, use the app password in the migration map. For details, go to Create & upload a migration map.

3. Verify the number of existing IMAP connections for users

If a user has existing IMAP connections, the IMAP server might reach its connection limit, and the new data migration service won't be able to connect. To troubleshoot, remove the other IMAP connections for the user and try again.

General troubleshooting help

Error uploading map

You might get one of the following errors when uploading the migration map:

Error message	Steps to troubleshoot
Entry already exists	You added a source email address more than once. Check your migration map for duplicated source users (it's OK to list the target user more than once).
Target Gmail Account Entity must be set	A target email address is missing. Check the CSV file for missing target users.
Email ID for Gmail Account entity must be set and valid	Ensure that the email addresses in the file are set and use valid email formats.

Migration fails to start

Make sure that a target domain super admin starts the migration. The new data migration service requires super admin privileges as it grants domain-wide delegation in the target domain before it begins to migrate data.

Migration completes, but there are failed items

Click Export migration report and use the report to identify items that didn't migrate and the reasons for the failure. For details, go to Understand the new data migration service reports.

Fix the issues, then Run a delta migration.

Missing messages

If you can't find some messages after a migration, work through the following troubleshooting steps.

Step 1: Make sure a message isn't mislabeled

1. Get the message-ID of a missing message from the source account.

   For details on finding the message-ID, go to Trace an email with its full header.

2. In the target account, use the rfc822msgid: Gmail search operator to search for the message-ID.

   For details on using a search operator, go to Refine searches in Gmail.

3. If the message can't be found, continue to the next step.

Step 2: Check the migration report

1. Export the migration report. For details, go to Export the reports.
2. Search for the missing message using its message-ID.
3. If the message shows as failed in the report, locate the error code in Common error messages.
4. Follow the instructions to troubleshoot the error message.

Error migrating labels

If you get an error when migrating labels, the message attached to the label migrates but in a warning state. Try running a delta migration to fix the issue. If the issue persists:

1. Choose an option:
   • Fix the issue with the label.

     To troubleshoot the label, go to Understand the new data migration service reports.

   • Remove the label.
2. Run a delta migration.