Help
Authentication failed: wrong or rotated credentials
Tested with:Databasezy API v1 · zb CLI 0.1
An authentication error means your client reached the database and the database refused the user name or password. The network, allow-list and TLS are working. The usual causes are a password that was rotated, a copy-and-paste mistake, the wrong user name, or a client setting that the gateway cannot support. If many logins fail in a short time, the gateway also blocks your IP address for a while, which looks like a connection problem instead.
password authentication failed, Access denied or WRONGPASS
Section titled “password authentication failed, Access denied or WRONGPASS”These messages come from the engine itself, for example:
- PostgreSQL:
FATAL: password authentication failed for user "..." - MySQL and MariaDB:
ERROR 1045 (28000): Access denied for user '...' - Valkey and Redis:
WRONGPASS invalid username-password pair
Check, in this order:
- The password is current. Someone may have rotated it. Rotations are recorded in the audit log.
- The user name is exactly the one shown for the instance (Connect page, or the reveal output below). Do not
assume
postgresorroot. - Special characters are encoded. In a connection URI, a password containing characters such as
@,:,/,?,#or%must be percent-encoded. Passing the password as a separate parameter avoids this. - The right secret reached the application. Check the environment variable or secret your deployment actually uses, and redeploy after changing it.
You lost the password
Section titled “You lost the password”Credentials are shown once when the instance is created. Databasezy does not store them in the control plane, so support cannot read them to you. You can reveal them again or replace them:
zb instances credentials reveal <instance_id> # prints the current credentials oncezb instances credentials rotate <instance_id> # replaces themBoth need the credentials permission and, if you turned on two-factor authentication or your organization requires it, a recent two-factor check. Reveals are rate limited, and both actions are recorded in the audit log. You can also use Instance → Connect in the portal.
To test the credentials without copying them anywhere, run zb connect <instance_id>. It opens the engine’s shell
with a one-time credential that is never written to disk or shell history.
The password was rotated
Section titled “The password was rotated”After a rotation, how long the old password keeps working depends on the engine:
| Engine | Old password accepted for new connections |
|---|---|
| MySQL | 10 minutes |
| Valkey | 10 minutes (the database restarts, so open connections must reconnect) |
| Other engines that support rotation | No overlap: the old password stops working straight away |
Update every application, job and tool that uses the instance. See Rotating credentials for the full procedure.
PostgreSQL: SCRAM and channel binding
Section titled “PostgreSQL: SCRAM and channel binding”PostgreSQL instances store passwords as scram-sha-256.
channel_binding=requirealways fails. The gateway terminates TLS and opens its own TLS session to the database, so channel binding cannot be verified and the gateway removes it from the offered mechanisms. Use the libpq defaultchannel_binding=prefer, ordisable. Plain SCRAM still never sends the password itself.- Very old clients that do not support SCRAM fail with an error such as
authentication method 10 not supported. Upgrade the driver or libpq (version 10 or later).
MySQL: caching_sha2_password
Section titled “MySQL: caching_sha2_password”MySQL 8.4 uses caching_sha2_password. It needs TLS or the server’s public key; on Databasezy TLS is always on, so
make sure your client connects with --ssl-mode=REQUIRED or stricter. A client that does not support this plugin
needs an upgrade.
Your IP is temporarily blocked after failed logins
Section titled “Your IP is temporarily blocked after failed logins”The gateway counts failed logins per client IP address. By default, 10 failures within a minute block that address for 10 minutes. While blocked, every new connection from it is closed straight away with no error message, even with the right password.
Fix: stop the process that is retrying with the wrong password (a crash-looping container is the usual source), fix the credential, and wait for the block to expire. Retrying sooner does not help.
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 user name you connect as, 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.