Skip to content

Help

A migration failed

Tested with:Databasezy API v1 · zb CLI 0.1

Start with zb migrate status <mig_id>. It shows the migration’s status, progress, the preflight checklist with a machine code on each item, verification results and, for continuous sync, the lag. Most failures are caught by preflight before anything is written. The CLI’s exit code also tells you which kind of failure it was.

shell
zb migrate status <mig_id>
zb migrate --from <source> --to <instance_id> --dry-run # rerun the offline checks and print the plan

A migration moves through pending, preflight, copying, verifying, then either completed or (for continuous sync) syncing, ready_for_cutover, cutting_over and completed. It can end as failed or cancelled.

Exit codeMeaning
1Preflight blockers, a failed migration, an abandoned cutover, or a local server version that is refused
2The request was rejected as invalid (a flag or source the API does not accept)
3Verification found a mismatch between source and target
4You answered no at a prompt
5The API could not be reached
6A local prerequisite is missing: the dump tool, docker, wrangler, a running container, or a local server that does not answer

Each preflight item has a code. The common ones:

CodeCauseFix
source.same_cell_gatewayThe connection string points to the target cell’s public Databasezy gatewaySelect Another Databasezy instance or use zb migrate --from inst_<source> --to inst_<target>. Changing the source firewall will not fix this route
private_endpointThe source host is private, loopback or provider-internal, so the migration job cannot reach itUse the provider’s public endpoint, or run zb migrate --from local on a machine that can reach it
pg.wal_levelContinuous sync needs wal_level = logical on the PostgreSQL sourceChange the setting (the message says how for your provider) and restart the source, or use --mode copy
pg.replica_identityTables without a primary key block PostgreSQL syncAdd a primary key, or ALTER TABLE ... REPLICA IDENTITY FULL
replication.privilegeThe source user may not replicateGrant the replication privilege, or use --mode copy
replication.platform_login, replication.platform_login_missingThe source is another Databasezy instance and its per-migration replication login was not ready, or not providedStart the migration again; see instance-to-instance sync
sync_login_unavailableThe replication login on the source instance could not be prepared in time; nothing was copiedStart the migration again; contact support with the migration ID if it keeps failing
sync_wal_boundThe target fell behind until the source’s replication slot reached its WAL limit; the slot was droppedFix what stopped the target (paused, full, apply error) and start again
mysql.log_bin, mysql.binlog_format, mysql.gtid_mode, mysql.replication_grantMySQL sync needs binary logging, row-based binlogs, GTIDs and the REPLICATION SLAVE grantChange the source settings, or use --mode copy
sync.mariadbMariaDB supports copy onlyUse --mode copy
sync.unsupported_engineContinuous sync is for PostgreSQL, TimescaleDB and MySQL targets onlyUse --mode copy
target.database_missingThe database you named does not exist on the instanceRestore into the instance’s own database
egress.unknownThe region has not published fixed egress addresses to put on your source’s firewallLet the source accept TLS connections from any address during the migration, or use --from local
egress.allowlist, <provider>.allowlistThe addresses the copy connects from, to allow on the sourceAdd them to the source’s firewall or IP access list (also listed by GET /v1/regions/<region>/egress)
tls.verify_disabledThe URL turns certificate verification off (skip_verify, tlsInsecure, tlsAllowInvalid...) or names a CA file on the agentRemove the option; for a self-signed or private-CA source pass --ca-file ca.pem
source.ca_pem (field error)The CA upload is not usable: a private key, not PEM, expired, not a CA or self-signed certificate, over 64 KiB, --mode copy_and_sync, or a source without TLSUpload only the CA certificate, use --mode copy and a TLS URL (rediss://, sslmode other than disable)

The copy connects out from the cell that hosts your target, not from your computer. When preflight shows an egress.allowlist (or <provider>.allowlist) item, add the addresses it lists to the source’s firewall, security group or IP access list (the migration wizard shows the same list before you start). A TLS error such as certificate verify failed or self-signed certificate means the source’s certificate is not signed by a public CA: pass its CA with --ca-file. Use the provider’s direct endpoint, not a connection pooler; the provider presets rewrite the common ones for you. See How migrations work.

--from local runs the engine’s own dump tool on your machine. Install it with the command the CLI prints, or run it inside a Docker container that already has it: --container <name>. See zb migrate CLI.

Verification found a mismatch (exit code 3)

Section titled “Verification found a mismatch (exit code 3)”

Row counts, sequences, indexes or the schema differ. With --mode copy, the usual cause is that the source kept changing during the copy. Stop writes to the source and run the migration again with --drop-target, or use --mode copy_and_sync (PostgreSQL, TimescaleDB, MySQL) so the target keeps up until you cut over.

The CLI stops waiting when a migration stays pending for 20 minutes with no report from the cell, when nothing changes for 6 hours, or after --timeout (24 hours by default). The migration itself keeps running. Check it with zb migrate status <mig_id>, or stop it with zb migrate cancel <mig_id>. A migration stuck in pending usually means the migration job could not start; open a ticket with the migration id.

If the target cannot catch up within 120 seconds, or the final check finds a difference, the cutover is abandoned. Nothing changes on either side and sync keeps running. Make sure every writer to the source is really stopped, then run zb migrate cutover <mig_id> again.

  • 409 Conflict: another migration into the same instance is already running. One at a time per target.
  • A mode error: continuous sync needs a target on a paid plan; Free instances sleep when idle.
  • Objects already exist in the target: run again with --drop-target to drop them first.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket). Include the migration id, the target instance id, the source provider and engine version, the failing preflight code or the exact error text, the CLI exit code, and the time it happened in UTC. Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.