Help
Troubleshooting
Tested with:Databasezy API v1 · zb CLI 0.1
Most problems fall into a few groups: the client cannot reach the instance, the instance refuses the login, it is out of connections or resources, or it is paused. Check the instance’s status first, then open the article that matches the error text you see. Every article starts with the most likely cause.
Check the instance status first
Section titled “Check the instance status first”Many errors are just an instance that is not running yet, or not running any more.
zb instances get <instance_id>The status column shows what the instance is doing now, and a message: line explains a failure. The statuses you
will see:
| Status | Meaning |
|---|---|
requested, provisioning | Being created. Connections fail until it is ready |
ready | Running and accepting connections |
modifying | A resize, storage grow or upgrade is in progress |
restoring | A restore is running |
paused, archived | Compute is stopped. See Paused and waking instances |
suspended | Stopped for billing or a quota. See Spending caps and quota errors |
failed | Something went wrong. Read the message, then open a ticket if it is not clear |
In the portal, open the instance and look at the header and the Timeline tab for recent changes. From the CLI,
zb logs <instance_id> -f streams the instance’s events (status changes, backups, migrations). Engine logs are not
available through the API yet.
Connection problems
Section titled “Connection problems”- Cannot connect, timeouts and connection refused: wrong host or port, instance not ready, firewalls, and connections that close with no error.
- TLS and certificate errors:
certificate verify failed, hostname mismatch, SNI, old TLS versions and the CA bundle. - Blocked by the IP allow-list: CIDR format, IPv6, and serverless platforms without fixed addresses.
- Authentication failed: wrong or rotated passwords, user names, SCRAM and channel binding, temporary IP blocks.
- Too many connections: connection limits per size, pool sizing and the PostgreSQL pooler.
Instance state and performance
Section titled “Instance state and performance”- Paused and waking instances: why an instance is paused, how waking works and how long it takes.
- Slow queries, CPU, memory and full disks: reading the Metrics tab, growing storage and resizing.
Backups and restores
Section titled “Backups and restores”- Restore a backup: into a new instance or in place.
- Point-in-time recovery: which engines and plans have it, and its errors.
- A backup failed or is missing: what your plan backs up and why a backup did not run.
Migrations
Section titled “Migrations”- Before you migrate: a checklist to run through first.
- A migration failed: preflight codes, stuck migrations, verification mismatches and abandoned cutovers.
Engine-specific errors
Section titled “Engine-specific errors”Each engine has its own error messages. See Engine errors for PostgreSQL, MySQL, Valkey and the other engines.
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 instance id, the region, the exact error text, your client or driver version, 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.