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 "" 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 ""  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

Monitor partitions

As you run a scan or bridge, you can monitor the status of the partitions. 

  1. In the G Suite Migrate platform, click Scans or Bridges.
  2. On the scan or bridge you want to check, click Logs ""and thenPartition log.
  3. Under State, check the status of the partitions:
    • Ready—Ready to begin.
    • Starting—Preparing to migrate or scan.
    • Crawling—Reading data from the source system.
    • Processing—Preparing to write data to the target system.
    • Committing—Writing data to the target system.
    • Cancelled—Failed. Proceed to Troubleshoot canceled partitions.
    • Completed—Finished working.
    • Skipped—Partition hasn’t been used in the execution.
Troubleshoot canceled partitions

Option 1: Check error codes

To see the error codes, point to a row in the partition log and click ""and thenPartition log. Use the error code associated with the failure to troubleshoot the issue. For details, see Interpret G Suite Migrate error messages.

Option 2: Check the nodes

Use the partition log to see whether all partitions on a specific node are canceled. The name of the node is listed in the partition log under Executing node

Canceled nodes usually indicate connection issues, for example, the temporary unavailability of the source service. Complete the steps in Troubleshoot node status. Then, retry the scan or run a delta migration.

Option 3: Check the execution log

If the issue affects multiple nodes, you can investigate further by examining the execution log which lists the failures associated with the scan or bridge. To see the execution log that's associated with a partition:

  1. Open the partition log.
  2. Point to a row in the log and click ""and thenExecution log.
  3. Under State, check the Failed box. 
  4. Use those failures to isolate and troubleshoot the cause of the problem.
  5. Retry the scan or 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 "" 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 "" and select Transaction log.
  3. Click Filter "" .
  4. Uncheck the default filter boxes and check the Running box.
  5. Click Apply filters.

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 "").
  • 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