Troubleshoot an email migration

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

• Troubleshoot migrations from Google Workspace
• Troubleshoot migrations from an IMAP server
• Troubleshoot migrations from Gmail accounts
• 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.
4. If the client ID entry is missing or you can't find the authorization request email, exit the migration and reauthorize the source account.

   For details, go to Request authorization.

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.

Troubleshoot migrations from Gmail accounts

If you have issues migrating data from a Gmail account, start with these steps.

1. Check the email address of the user

Make sure you entered a correct and valid email address for the consumer Gmail user.

2. Verify that the user has given consent to migration

In your Google Admin console, click Verify Authorization and make sure you get a Connected notification, which indicates that the connection is authorized. If the user has rejected the request, you get an Authorization Denied message.

If the user denies the request after having approved it, the connection moves from a Connected state to an Authorization denied state. In that state, you won't be able to start a migration. If the migration is already running when the user revokes their consent, the migration eventually stops, and the migration report shows errors that indicate the user denied the authorization request.

3. Check that the email link is valid

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

General troubleshooting help

Error uploading map

You might get one of the following errors when uploading the migration map when you set up a migration from Google Workspace:

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 you can't find the message, 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 Resolve common error messages.
4. Follow the instructions to troubleshoot the error message.

Error migrating labels

If you get an error when migrating labels, you might get the following issues:

• For migrations from Google Workspace or a consumer Gmail account, the message attached to the label migrates but in a warning state.
• For migrations from an IMAP server, the message is skipped if the parent label doesn't migrate.

To troubleshoot, try running a delta migration. 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.