This article explains how to resolve the NotFound[404] error that causes user migrations to fail when migrating data between two Google Workspace tenants.
1. Symptom
When running a Google Drive to Google Drive migration, one or more users fail completely. The migration log for the affected user displays an exception message similar to this:
Unexpected exception when processing user. Unexpected exception processing import. Message is: Not retrying NotFound[404] error cloud.solutions.Migration.Core.ImportThreadException
This error indicates that CloudM Migrate attempted to apply permissions to a file or folder in the destination, but the user or group it tried to share with could not be found.
2. Cause
The root cause of the NotFound[404] error in this scenario, is highly likely an unresolvable permission. During the migration, CloudM Migrate reads the permissions of a source file or folder. It then tries to replicate those exact permissions in the destination. The error occurs when a user or group that has access in the source does not exist in the destination environment.
Because preserving the folder structure and its permissions is critical for data integrity, CloudM Migrate intentionally fails the user's migration to prevent creating a broken or inaccessible folder hierarchy in the destination. Continuing the migration would risk orphaning files and creating inconsistencies for other users who share the same items.
3. Resolution
To prevent and resolve this error, you must ensure that the destination environment is a complete mirror of the source in terms of users, groups, and domain/address mappings before you begin migrating Drive data.
Step 1: Use the Migration Readiness Test
CloudM Migrate includes a built-in check to help you identify these issues proactively. Before starting a migration, you will be prompted to run the Migration Readiness tests.
This is designed to help prevent 404 errors by validating that users and groups are properly provisioned.
Step 2: Provision All Users and Groups
Ensure that ALL users and groups from the source tenant are created and active in the destination tenant. This includes:
-
All Users: Every user who owns data or has had data shared with them must exist in the destination.
-
All Groups: Every Google Group used for sharing must exist in the destination.
Step 3: Verify Address and Domain Replacements
CloudM Migrate must know how to map every email address from the source domain to the destination domain. This is handled via domain and address replacements.
Review your configuration for the following common scenarios:
-
Sub-domain Sharing: If a file is shared with
user@sub.source.com, you must have a domain replacement to mapsub.source.comtodestination.com. -
Alias Address Sharing: If a file is shared with a user's alias (
alias.name@source.com), you must have an address replacement entry mapping the alias to their primary address in the destination (primary.name@destination.com). -
'Replace CSV Addresses Only' Setting: If this feature is enabled, ensure that your domain replacements are also explicitly included in your Address Replacements CSV file.
You can find more information on address replacements here: Address Replacements
Step 4: Address Common Failure Scenarios
Review the following checklist, which covers the most frequent causes of this error:
-
Missing Google Group: A file is shared with a group that was not created in the destination.
-
Solution: Create the group in the destination and ensure its membership is correct.
-
-
Unmapped Sub-domain: A permission is tied to a sub-domain that isn't included in your Domain Replacements.
-
Solution: Add the sub-domain mapping (e.g.,
source.sub-domain.comtodestination.primarydomain.com).
-
-
Unmapped Alias: A permission is assigned to a user's alias address, which is not in your Address Replacements CSV.
-
Solution: Add the alias-to-primary mapping in your address replacements file.
-
Once you have corrected the provisioning or mapping issues, you can re-run the migration for the failed user.