Diagnose database connection failures
Test from the same runtime and network that runs the application. A successful dashboard page or a connection from your laptop does not prove the deployed application can connect.
Check in this order
- Confirm the database is active, not paused, creating, error or deleted.
- Read the public host/port and native database name from connection details. Do not use the management API hostname or the human display name.
- Check DNS and outbound connectivity to that host/port from the application runtime.
- Verify the application’s outbound IP against the configured CIDRs and inspect
allowlist_enforced. - Check the exact returned username, current password and URI encoding. A masked
****URI cannot authenticate. - Verify TLS mode, hostname and CA trust without disabling certificate checks.
- Run the smallest engine example, then add application-specific queries and permissions.
| Error or behavior | Likely cause / check |
|---|---|
| Connection refused or timeout | Wrong host/port, paused database, network policy, engine availability |
| TLS/certificate failure | Wrong host, missing CA, incompatible mode or TLS unavailable; resolve configuration with support |
| PostgreSQL authentication failure | Namespaced username, password/encoding, selected native database |
| PostgreSQL permission denied after metadata change | Existing engine grants were not updated; use the documented credential replacement workflow |
| Too many connections | Combined pools, leaking clients, replicas, migrations; bound pools and release clients |
Redis WRONGPASS | ACL username/password and credential state |
Redis NOPERM | Missing/wrong key prefix or a command prohibited by the ACL |
| Redis key seems missing | Wrong or doubled prefix, expired key, different application key convention |
| MongoDB authentication failed | Exact database-scoped username, password and authSource |
| MongoDB server selection timeout | Destination, network, TLS, resource state; inspect the underlying driver error |
| User creation returns a nonworking URI | Masked password or non-public destination; construct from user credentials plus public connection details |
A database password reset does not automatically update running applications. Update the injected secret and establish a new connection. Avoid printing full driver configuration while debugging.
If the minimal example still fails, share engine, sanitized destination, resource UUID, UTC time, driver error code/class and source network with support. Do not share the password or connection URI.