Skip to content

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 standard SSLRequest negotiation. Remove the option, or set it to postgres.
  • 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.

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.