Connection errors
Fix common backupd connection errors, from invalid connection strings and TLS to private addresses, rejected credentials and unreachable hosts.
When you click Connect database, backupd only checks that the connection string is well formed. The first real connection happens on the first backup, so most connection problems show up as a failed backup with one of the messages below. Click Backup now after adding a database to find out straight away.
Connection string format
That connection string isn't a valid URL
The string couldn't be parsed. Check for spaces, and percent-encode special characters in the user or password (@ as %40, / as %2F, : as %3A, # as %23).
A postgres connection string starts with postgres:// or postgresql://
The scheme doesn't match the engine you picked. MySQL strings start with mysql://, MongoDB strings with mongodb:// or mongodb+srv://.
Add the database name to the connection string (mysql://user:pass@host:3306/database)
MySQL connections back up one database each. Add its name to the path.
Use your deployment URL, e.g. https://happy-otter-123.convex.cloud
For Convex Cloud, enter the deployment URL, not the dashboard URL. For a self-hosted backend, choose the Self-hosted tab.
Use an https:// deployment URL
Convex deployments must be reached over HTTPS.
The connection option "…" isn't supported
The MongoDB connection string has an option backupd doesn't accept. Remove it. See the supported options.
Use SCRAM authentication (authMechanism=SCRAM-SHA-256)
MongoDB connections must use SCRAM. Remove other authMechanism values.
TLS
backupd connects over TLS; remove sslmode=disable
PostgreSQL. Remove sslmode=disable, or set sslmode=require. The server must accept TLS connections.
backupd connects over TLS; remove ssl-mode=DISABLED
MySQL. Remove ssl-mode=DISABLED, or set ssl-mode=REQUIRED.
backupd connects over TLS; add tls=true to the connection string
MongoDB with a mongodb:// address. Add tls=true, or use the mongodb+srv:// address your provider gives you.
Unknown sslmode "…" or Unknown ssl-mode "…"
Use one of the supported values: require, verify-ca or verify-full for PostgreSQL, REQUIRED, VERIFY_CA or VERIFY_IDENTITY for MySQL.
Network
db.internal:5432 resolves to a private or reserved address, which backupd can't reach
The host resolves to a private, loopback or link-local address. backupd only connects to public addresses. Use your database's public hostname. Private networks and SSH tunnels aren't supported yet.
Couldn't resolve db.example.com or Couldn't resolve the SRV record
The hostname doesn't exist in DNS. Check it for typos, and that the database's public endpoint is turned on.
Couldn't reach the database
backupd couldn't open a connection. Check that the database is running, that the port is right, and that your firewall or your provider's allow list includes backupd's addresses. This error is retried automatically.
Couldn't connect to PostgreSQL: timed out (or MySQL, MongoDB)
The connection didn't complete in time. Usually a firewall silently dropping the connection. Allow backupd's addresses through.
Credentials and permissions
The database rejected backupd's credentials
The user or password is wrong, or the server doesn't allow this user to connect from outside (for PostgreSQL, a missing pg_hba.conf entry). Connection strings can't be edited, so add the database again with the right credentials. See Change the connection string.
The backup user is missing a privilege
The user can connect but can't read everything. Grant the permissions for your engine: PostgreSQL, MySQL, MongoDB.
Convex rejected the deploy key
The key is wrong, revoked or for another deployment. Create a new production deploy key in the Convex dashboard. For self-hosted backends, generate a new admin key.
The deploy key can't export or import data
Use a production deploy key, or an admin key for self-hosted Convex.
Versions
PostgreSQL … isn't supported
backupd supports PostgreSQL 9.2 to 18. The message names your server's version.
… isn't supported (MySQL 5.7+ or MariaDB 10.3+)
backupd supports MySQL 5.7 and later and MariaDB 10.3 and later. Upgrade the server to back it up with backupd.
MongoDB … isn't supported (4.2+)
backupd supports MongoDB 4.2 and later.