Troubleshoot G Suite Migrate

Here’s how to troubleshoot problems you might encounter while configuring G Suite Migrate and running a migration.

Open all   |   Close all

First, try these troubleshooting options

Run a bridge as a delta migration

You can often fix a large number of errors without any additional configuration or troubleshooting by running a bridge as a delta migration.

Running a bridge as a delta migration can identify persistent errors and clean up transient (temporary) errors, such as rate limiting and quota levels enforced on the source and target environment, networking issues, and 401 Unauthorized errors on specific resources. You can rerun bridges multiple times to troubleshoot. Learn more

Review the migration summary logs

You can use the migration summary logs to see a high-level overview of the migrated content and the total number of transactions processed. Use the summary logs as your main starting point for troubleshooting G Suite Migrate.

Migration summary data is grouped into several categories: by identity or user (the default), by source type, and by error. You can use the categories to identify source domain data that might cause potential bottlenecks. For example, if you group by error code, you might see that there is an unexpectedly high count of a single error.

When troubleshooting problems, you can use a top-down approach (look at overall trends) or a bottom-up approach (investigate issues for a specific user).

To view migration summary data:

  1. Open the G Suite Migrate platform and click Bridges.
  2. Click Logs Logs and select Migration Summary.
  3. From the Group By menu, select a category.
  4. (Optional) To narrow your search results further:
    1. From the Group By menu, select another category.
    2. Click Filter Filter  to apply a column filter.
  5. On a record, click the ellipsis (...) and select Logs.
    You’ll see the transaction log and detailed records of your data set, including stack traces and error codes.

Troubleshoot association or connection errors

Verify that the nodes are running
  1. Sign in to the G Suite Migrate platform and in the top-right corner, click Servers
  2. Verify that your nodes appear in the list.
  3. Check that the status of the nodes is Ready.
Troubleshoot node status

If you get an error when trying to associate a node with the G Suite Migrate platform, first check whether the node is running:

  1. In a browser on the machine that is running the platform, enter the node's IP address (for example, http://192.168.1.5:5131).
  2. Check to see whether the node is associated correctly.

    If so, you'll see a message saying "Node is running."

  3. If you see an error, first make sure no actions are running or queued on the node. Then, try the following options:
    • If it's a network error, resolve it and try again to associate the node.
    • Restart the node application.
    • Set up a new node:
      1. Reinstall the node application.
      2. (Optional) If you're using Google Compute Engine, clone the node. 
      3. Associate the nodes with the G Suite Migrate platform. 
Check the service host logs

If you suspect a deployment-configuration issue, check the service host logs.

  1. Find the logs:
    • On a platform installation—Go to C:\Program Files\G Suite Migrate\G Suite Migrate Platform\AppBridgeServiceHost.log.
    • On a node installation—Go to C:\Program Files\G Suite Migrate\G Suite Migrate Platform Node\AppBridgeServiceHost.log.
  2. Open the log and scroll to the end.
  3. If there are relevant issues listed, troubleshoot the issues.
  4. If you can't fix the issue, see Still need help? 
G Suite connection errors

If you're getting G Suite connection errors, it might be related to problems with your service account or API set up. A service account connection allows you to connect to your target G Suite domain.

To troubleshoot this problem:

  1. If you see an “invalid grant” message when you attempt to add a service account in the Google Cloud Platform (GCP) Console, ensure you enabled all the APIs. Learn more
  2. If you see an “invalid client ID” message, make sure you:
    1. Authorized all of the API scopes for your target environment. Learn more
    2. Use your OAuth 2.0 client ID for authorization and not your service account's client ID. Learn more
  3. If your migration is running slowly or not at all, the error might be related to G Suite’s API quota levels. Learn more

Track the health and progress of a migration

Troubleshoot escalating failure rates

If you see an increase in similar failures in the migration summary, your migration configuration is probably incorrect. You should always check the migration summary for user and source errors to see if there are any categories with high error rates.

Check the following configuration items to make sure they are correctly set up:

  1. Ensure the APIs, particularly the Admin SDK, are correctly enabled in the Google Admin console. Learn more
  2. Verify all users have the necessary G Suite services (for example, Gmail or Google Drive) turned on. Learn more
  3. Complete all steps for basic user verification. For details, see the User validation steps below.
Quickly filter transaction logs

You can see a detailed record of each object processed during a bridge using the transaction logs. However, with a typical migration generating hundreds of millions of objects, the log can take a long time to load and is difficult to filter.

To quickly see filtered transaction logs:

  1. Open the G Suite Migrate platform and click Bridges.
  2. On a bridge card, click Completed, Warning, Failed, or Skipped to filter the log data and see scoped-down data for that category.
  3. Click Filter Filter to refine the data further.
View the transaction log in real time

During a migration, object records are constantly being written to the transaction log. You can see these log records in real time to spot check the migration and ensure there are no major problems.

To see the current stream of migrated objects in the transaction log:

  1. Open the G Suite Migrate platform and click Bridges.
  2. Click Logs Logs and select Transaction log.
  3. Click Filter Filter .
  4. Uncheck the default filter boxes and check the Running box.
  5. Click Apply filters.

Troubleshoot an Exchange connection

Exchange connection errors

To troubleshoot your Microsoft® Exchange® connection, make sure you: 

  • Meet all the system requirements for Exchange. Learn more
  • Have the correct Exchange administrator credentials. If the credentials changed, enter the new credentials and try again.
  • Use a third-party tool like EWSEditor to check if you can connect to your Exchange server from all servers running G Suite Migrate.

    Note: G Suite Migrate uses the same Exchange Web Services (EWS) connection method as EWSEditor. If the tool fails to connect, G Suite Migrate will not successfully connect. Work with your Exchange admin to resolve these connection issues.

    Third-party tools are not supported by Google. Problems with a third-party tool must be handled by the third-party vendor.
User validation

To complete basic user validation, make sure the user account:

  • Exists in Exchange and in G Suite.
  • Is not frozen, suspended, or renamed.
Duplicate email messages

If you use email forwarding and the Accelerate Old Messages setting is turned on, set the Insert Before Date field to one day before email forwarding was turned on. G Suite Migrate will use this date to check that incoming email messages don’t already exist in the target mailbox.

For details on how to copy Exchange content using the Accelerate Old Messages setting, see Understand Exchange settings templates.

Exchange email filters

If your Exchange server uses complex filters, you might not see certain filters and actions migrated into G Suite. Not all Exchange actions and conditions map to a Gmail equivalent.

For a list of the Exchange filters that are not migrated, see Watchpoints and best practices for Exchange.

Missing organizer on Exchange calendars

If you see a 400 error relating to Exchange calendars, make sure the original event organizer was not removed from Exchange. If they were, use the settings template for Exchange to assign a default email address and to set a suffix in the calendar event to reset the organizer.

For details, see Use a settings template.

Recover data in the event of a failure

Use the encryption key to recover data

If a platform failure occurs, you can recover existing migration data using the encryption key and password you specified when you set up G Suite Migrate. 

To recover the data, you need to set up a new platform:

  1. Download and install the platform. For details, see Install and set up the platform.
  2. Open Chrome Browser and using the http(s)://localhost:<port> format, enter the URL of the G Suite Migrate platform. 
  3. Using the same admin account that you used to authorize your service account’s client ID, sign in to the platform.
  4. Click Get started
  5. Click I want to recover previous migration data
  6. In the Password field, enter your encryption key password. 
  7. Click Upload CSV file to upload the encryption key or drag the file to the box.
  8. Click Recover key
  9. Using the same database settings that you used when you first set up G Suite Migrate, complete the steps in Configure database settings.
  10. Using the same callback addresses and nodes that you used when you first set up G Suite Migrate, continue through the setup process.

Once you have completed the recovery process, you can access all your old projects, settings, and logs that are stored on the databases.

Still need help?

If the information above didn't solve your problem, check the G Suite Migrate known issues.

If you still need help, contact G Suite support and include as much of the following information as possible:

  • Current G Suite Migrate version number (on the dashboard next to Help Help).
  • Customer domain name.
  • Deployment environment, such as GCP, on premises, third-party cloud provider.
  • Issue date and time (including time zone).
  • Description of the issue, including what’s happening versus what you expect to happen.
  • List of steps that causes the issue.
  • If the issue affects users, include an email address or username.
  • Screenshots of all error messages in G Suite Migrate. Additionally, you might be asked to provide screenshots of your platform settings.
  • An export of the migration summary. For details, see the Review the migration summary logs steps above.
  • Copies of the service host log from the G Suite Migrate platform and node server. You can find the log:
    • On a platform installation—Go to C:\Program Files\G Suite Migrate\G Suite Migrate Platform\AppBridgeServiceHost.log.
    • On a node installation—Go to C:\Program Files\G Suite Migrate\G Suite Migrate Platform Node\AppBridgeServiceHost.log.

We might also route your issue to a specialized team for further investigation. Resolution times vary, depending on the complexity of your issue and the availability of troubleshooting data.

Related topics