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.
zb migrate status <mig_id>zb migrate --from <source> --to <instance_id> --dry-run # rerun the offline checks and print the planA 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.
What the exit code means
Section titled “What the exit code means”| Exit code | Meaning |
|---|---|
1 | Preflight blockers, a failed migration, an abandoned cutover, or a local server version that is refused |
2 | The request was rejected as invalid (a flag or source the API does not accept) |
3 | Verification found a mismatch between source and target |
4 | You answered no at a prompt |
5 | The API could not be reached |
6 | A local prerequisite is missing: the dump tool, docker, wrangler, a running container, or a local server that does not answer |
Preflight failed
Section titled “Preflight failed”Each preflight item has a code. The common ones:
| Code | Cause | Fix |
|---|---|---|
source.same_cell_gateway | The connection string points to the target cell’s public Databasezy gateway | Select Another Databasezy instance or use zb migrate --from inst_<source> --to inst_<target>. Changing the source firewall will not fix this route |
private_endpoint | The source host is private, loopback or provider-internal, so the migration job cannot reach it | Use the provider’s public endpoint, or run zb migrate --from local on a machine that can reach it |
pg.wal_level | Continuous sync needs wal_level = logical on the PostgreSQL source | Change the setting (the message says how for your provider) and restart the source, or use --mode copy |
pg.replica_identity | Tables without a primary key block PostgreSQL sync | Add a primary key, or ALTER TABLE ... REPLICA IDENTITY FULL |
replication.privilege | The source user may not replicate | Grant the replication privilege, or use --mode copy |
replication.platform_login, replication.platform_login_missing | The source is another Databasezy instance and its per-migration replication login was not ready, or not provided | Start the migration again; see instance-to-instance sync |
sync_login_unavailable | The replication login on the source instance could not be prepared in time; nothing was copied | Start the migration again; contact support with the migration ID if it keeps failing |
sync_wal_bound | The target fell behind until the source’s replication slot reached its WAL limit; the slot was dropped | Fix what stopped the target (paused, full, apply error) and start again |
mysql.log_bin, mysql.binlog_format, mysql.gtid_mode, mysql.replication_grant | MySQL sync needs binary logging, row-based binlogs, GTIDs and the REPLICATION SLAVE grant | Change the source settings, or use --mode copy |
sync.mariadb | MariaDB supports copy only | Use --mode copy |
sync.unsupported_engine | Continuous sync is for PostgreSQL, TimescaleDB and MySQL targets only | Use --mode copy |
target.database_missing | The database you named does not exist on the instance | Restore into the instance’s own database |
egress.unknown | The region has not published fixed egress addresses to put on your source’s firewall | Let the source accept TLS connections from any address during the migration, or use --from local |
egress.allowlist, <provider>.allowlist | The addresses the copy connects from, to allow on the source | Add them to the source’s firewall or IP access list (also listed by GET /v1/regions/<region>/egress) |
tls.verify_disabled | The URL turns certificate verification off (skip_verify, tlsInsecure, tlsAllowInvalid...) or names a CA file on the agent | Remove 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 TLS | Upload only the CA certificate, use --mode copy and a TLS URL (rediss://, sslmode other than disable) |
The source refuses the connection
Section titled “The source refuses the connection”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.
`pg_dump` is not installed (exit code 6)
Section titled “`pg_dump` is not installed (exit code 6)”--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 stopped following
Section titled “The CLI stopped following”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.
Cutover was abandoned
Section titled “Cutover was abandoned”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.
Other refusals
Section titled “Other refusals”409 Conflict: another migration into the same instance is already running. One at a time per target.- A
modeerror: continuous sync needs a target on a paid plan; Free instances sleep when idle. - Objects already exist in the target: run again with
--drop-targetto drop them first.
Still stuck?
Section titled “Still stuck?”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.