Help
PostgreSQL errors and how to fix them
Tested with:PostgreSQL 18 on Databasezy · zb CLI 0.1
PostgreSQL is available on every plan, including Free. Errors come from the Databasezy gateway in front of the
instance or from PostgreSQL itself. Gateway errors arrive as normal FATAL messages. Everything here also applies to
TimescaleDB; its own errors are on InfluxDB, QuestDB and TimescaleDB errors.
FATAL: SSL/TLS is required; use sslmode=require or verify-full
Section titled “FATAL: SSL/TLS is required; use sslmode=require or verify-full”Cause: the client tried to connect without TLS (for example sslmode=disable, or a driver whose TLS is off by
default). The gateway never accepts plaintext.
Fix: set sslmode=verify-full and pass the CA bundle with sslrootcert. libpq-based clients (psql, psycopg,
Ruby pg, PHP pgsql) do not read the system trust store. See Connect to PostgreSQL.
Connection closed during the TLS handshake
Section titled “Connection closed during the TLS handshake”You may see SSL SYSCALL error: EOF detected, server closed the connection unexpectedly, or a TLS handshake error.
The gateway closes the connection without sending a PostgreSQL message in these cases:
- Your address is not on the allow-list. Add your egress IP or CIDR under Network → IP allow-list. See IP allow-lists.
- You connected by IP address or to the wrong host name. The gateway routes by the TLS server name (SNI). Use the exact host from the Connect tab.
- You set
sslnegotiation=direct. The gateway only supports the standardSSLRequestnegotiation. Remove the option, or set it topostgres. - Your address is temporarily blocked. By default, 10 failed logins from one address within a minute block that address for 10 minutes. Fix the password, then wait.
channel binding is required, but server did not offer an authentication method that supports channel binding
Section titled “channel binding is required, but server did not offer an authentication method that supports channel binding”Cause: the client sets channel_binding=require. The gateway terminates TLS, so channel binding could never verify.
It therefore removes SCRAM-SHA-256-PLUS from the offer. Your password is still checked with SCRAM-SHA-256.
Fix: remove channel_binding=require, or set it to prefer (the libpq default).
FATAL: password authentication failed for user "app"
Section titled “FATAL: password authentication failed for user "app"”Cause: this error comes from PostgreSQL. The password is wrong, or it was rotated. Every instance has one user,
app. After a rotation the old password stops working in PostgreSQL immediately.
Fix: reveal the current credential with zb instances credentials reveal <instance_id> or from Connect. Then
update your secret store. See Rotating credentials and
Authentication failed.
FATAL: too many connections for this instance
Section titled “FATAL: too many connections for this instance”Cause: the instance already has as many connections open as its size allows. The gateway caps them at the size’s
max_connections. connection rate limit exceeded; slow down means clients opened more than 50 new connections in
one second. If PostgreSQL turns the connection away itself, the message is sorry, too many clients already.
Fix: keep the total of your application pools under the limit. Use the built-in transaction-mode pooler for serverless and edge runtimes, or resize. See Connection pooling and Too many connections.
FATAL: the instance is waking up; retry in a few seconds or FATAL: paused: ...
Section titled “FATAL: the instance is waking up; retry in a few seconds or FATAL: paused: ...”Cause: “waking up” means a sleeping Free instance is waking. Free instances sleep after 15 minutes without
connections; the gateway holds the first connection for up to 30 seconds while the instance wakes, and you get this
error if it is not ready in time. paused: the instance is paused by its owner; resume it in the portal or with `zb instances resume` (SQLSTATE 08004) means someone paused the instance on purpose: connections
never wake it. paused: the instance was paused by Databasezy support; contact support to resume it means support paused it.
Fix: for “waking up”, retry with a connect timeout of at least 30 seconds. For a pause, run
zb instances resume <instance_id> (or contact support for a support pause). See
Paused and waking instances.
FATAL: suspended: the instance is suspended (...)
Section titled “FATAL: suspended: the instance is suspended (...)”Cause: billing suspended the instance, or it was archived after a long idle period on Free. If the message starts
with quota_exceeded:, a plan quota such as egress ran out.
Fix: see Spending caps and quota errors.
Cancelling a query does nothing (Ctrl+C, statement cancel, context cancel)
Section titled “Cancelling a query does nothing (Ctrl+C, statement cancel, context cancel)”Cause: PostgreSQL cancel requests open a separate connection without a TLS server name. The gateway cannot route them, so it refuses them.
Fix: set statement_timeout for the session or transaction. You can also run
select pg_cancel_backend(<pid>) from a second connection.
ERROR: canceling statement due to statement timeout
Section titled “ERROR: canceling statement due to statement timeout”Cause: on the Free plan, statement_timeout is 60 seconds. Paid plans set no statement timeout.
Fix: add an index or make the query smaller, or upgrade the plan. See Slow queries and resources.
FATAL: terminating connection due to idle-in-transaction timeout
Section titled “FATAL: terminating connection due to idle-in-transaction timeout”Cause: a session left a transaction open and idle for 5 minutes (idle_in_transaction_session_timeout, set on
every plan).
Fix: commit or roll back promptly, and do not hold transactions open across user requests.
permission denied to create role / permission denied to create database / must be superuser
Section titled “permission denied to create role / permission denied to create database / must be superuser”Cause: app owns the app database but is not a superuser, and it cannot create roles or databases directly.
Extensions that need elevated privileges, such as vector, pg_stat_statements and pgaudit, are installed
through the platform rather than create extension as app.
Fix: use Database users or zb instances users for managed read-only and read-write logins. Turn on
allow-listed extensions, including PostGIS and pg_cron, from Extensions or zb instances extensions;
availability depends on the PostgreSQL major and deployed image. See
PostgreSQL extensions.
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) and include:
- the instance id and region
- the exact error text
- your client or driver and its version
- your
sslmode - the time of the failure in UTC
Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.