Help
Cannot connect: timeouts and connection refused
Tested with:Databasezy API v1 · zb CLI 0.1
Every connection goes through the Databasezy gateway. The gateway checks the hostname, the IP allow-list and TLS before it reaches your database. A timeout or a silent disconnect almost always means one of four things: the wrong host or port, an instance that is not running, an IP address that is not on the allow-list, or a firewall on your side blocking the port. Work through the sections below in order.
Check the host and port
Section titled “Check the host and port”Copy the host and port from the instance’s Connect page in the portal, or from the endpoints list the API
returns. Do not build the hostname by hand.
The gateway listens on a small set of ports:
| Engine family | Port |
|---|---|
| PostgreSQL wire (PostgreSQL, TimescaleDB, QuestDB) | 5432 |
| MySQL, MariaDB | 3306 |
| Valkey, Redis | 6379 |
| MongoDB wire (MongoDB, FerretDB) | 27017 |
| HTTP and gRPC engines | 443 |
| ClickHouse | 8443 (HTTPS) and 9440 (native) |
Single-IP regions serve HTTP engines on 8443 instead of 443. The Connect page always shows the right port. See
Connecting to Databasezy for the details.
Do not connect by IP address. The gateway picks your instance from the hostname your client sends during the TLS handshake (SNI). A client that connects to an IP address sends no hostname, and the gateway closes the connection.
The instance is not ready
Section titled “The instance is not ready”zb instances get <instance_id>If the status is requested or provisioning, wait: new instances refuse connections until they are ready. If it
is paused, archived or suspended, see Paused and waking instances. If
it is failed, read the message: line and open a ticket if it is not clear.
The connection closes straight away, with no error message
Section titled “The connection closes straight away, with no error message”The gateway refuses some connections before TLS starts, so your client gets no database error at all. Drivers report
things like server closed the connection unexpectedly, SSL SYSCALL error: EOF detected, connection reset by peer, or a TLS handshake failure. The causes are:
- Your IP address is not on the allow-list. This is the most common cause. See Blocked by the IP allow-list.
- Your client sent no hostname (SNI). You connected by IP address, or your client is too old to send SNI. See TLS and certificate errors.
- Your IP address is temporarily blocked after many failed logins. See Authentication failed.
- The hostname is wrong, so no instance matches it. Copy it again from the Connect page.
The connection times out
Section titled “The connection times out”A timeout with no response at all usually means the packets never reach the gateway.
-
Corporate networks and cloud VPCs often block outbound traffic on database ports. Ask your network team to allow outbound TCP to the instance’s host on its port. Test from the same machine as your application:
shell nc -vz <host> 5432If
nccannot open the port, the block is on your side. -
Serverless platforms may need a NAT or static egress setting to reach the internet. See the platform guides.
-
Free-plan instances that are asleep hold the first connection for up to 30 seconds while they wake. A connect timeout shorter than that fails. Set it to at least 30 seconds.
Errors that mean “retry”
Section titled “Errors that mean “retry””The gateway sends these in your database’s own protocol. They are temporary:
the instance is waking up; retry in a few seconds: a sleeping Free-plan instance did not finish waking within 30 seconds. Retry.the instance is moving; retry in a few seconds: the instance is being moved or the gateway is restarting. Retry.instance unavailable; retry in a few seconds: the gateway could not reach the database behind it. Retry with backoff. If it lasts more than a few minutes, open a ticket.
Check with the CLI
Section titled “Check with the CLI”zb connect <instance_id> opens the engine’s shell (psql, mysql, valkey-cli, mongosh) with TLS and a
one-time credential. If zb connect works from your laptop but your application cannot connect, the problem is in
the application’s settings or network, not the instance.
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, the public IP address you connect from, 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.