--- cuppy_hub: gcp cuppy_path: reference/migration/errors.md cuppy_section: docs cuppy_doc: NVNF-NXTJ cuppy_doc_uuid: 77865a1e-87fc-4408-b9fa-597b82245eee cuppy_permalink: https://cuppy.io/gcp/d/NVNF-NXTJ cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/gcp/docs/reference/migration/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: e8953ead9d6844547101231559d3968ba3962769e9b9cb91787e63f345af6863 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # 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) | --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 91 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/gcp/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.