Migration error catalogue
No row here is a bug in a migration service. Every one is something about the destination that was not
prepared, which is why each names the family that owns the fix.
1. The migration cannot start at all
| |
|---|
| cause | the required API is not enabled on the project |
| check | gcloud services list on both the host project and the target project |
| fix | gcloud services enable SERVICE, with roles/serviceusage.serviceUsageAdmin. See reference/iac/errors.md §1 |
2. Permission errors naming a project you were not thinking about
| |
|---|
| cause | the host project "controls the migration process" and the target project "receives migrated resources" — two projects, two sets of permissions |
| check | read the project out of the error, then run Policy Troubleshooter against that project for the principal in the error |
| fix | grant on the project the error names. The split exists so the migration tooling need not be privileged everywhere; honour it rather than flattening it (guides/identity/fix-permission-denied.md) |
3. The migration runs and then stops part-way
| |
|---|
| cause | an allocation quota in the destination: CPUs, addresses, disks — all per project and often per region |
| check | read the live quota and the current usage (reference/overview/quotas-and-limits-model.md) |
| fix | request the increase before the wave, not during it. And check whether what you hit was a quota or a system limit — a system limit "cannot be increased or decreased" and needs a design change |
This is the commonest way a migration wave fails half-done, and it is entirely preventable: quota requests are
a pre-wave checklist item.
4. A database migration refuses the source
| |
|---|
| cause | the engine version is not on the supported list. "SQL Server is supported" is not a statement about your SQL Server |
| check | the separate supported-databases document — not read for this release, deliberately, because it is a living list |
| fix | upgrade the source first, or choose a different path. Both are schedule items, so find this out during assessment and not during the cut-over rehearsal |
And the related unknown: the page mentions "ongoing replication" without detailing CDC specifications, so
replication lag and DDL handling are not characterised in this hub. A cut-over window estimated without
reading them is a guess (reference/migration/database-migration-service.md §3).
5. The transfer saturates the source network
| |
|---|
| cause | an unthrottled agent fleet. Transfer agents exist precisely for "network routing control and bandwidth management" |
| check | is bandwidth limited on the agents? What else uses that link? |
| fix | throttle before you start. An unthrottled transfer out of a production data centre is an outage with a good explanation |
6. Data arrived, and something about it is wrong
| |
|---|
| cause | an overwrite or delete-after-transfer option set without being understood — behaviours the overview does not detail, so they must be read from the job configuration reference |
| check | the job's own configuration, before the run |
| fix | there may not be one. On a multi-terabyte transfer this is not a recoverable mistake; verify the configuration on a small prefix first |
7. The bill, which is not an error but arrives like one
| |
|---|
| cause | source-side egress, charged by the cloud the data is leaving; plus a destination storage class whose minimum duration started on arrival — ARCHIVE commits 365 days |
| check | estimate egress from the actual byte count before the wave; check the destination class against the data's real access pattern |
| fix | sequence waves to move each dataset once, and land in a class the access pattern justifies (reference/storage/cloud-storage.md §2) |
8. The zone was not part of the plan
| |
|---|
| cause | a migrated VM's zonal disk must be in the same zone as the instance, and a zonal disk does not move zones |
| check | what zone is the target instance in, and the target disk? |
| fix | fix it before cut-over. Afterwards it is a copy, not a reconfiguration (reference/overview/regions-zones-and-locations.md §3) |