Diagnosing DBeaver Connection Failures: From JDBC Drivers to SSL Handshakes

The Connection Failure Problem

A DBeaver connection failure typically manifests as a "Connection Refused," "Timeout," or "Access Denied" error when attempting to connect to a database. The primary challenge is that these errors often mask the root cause—whether it is a network firewall, an incompatible JDBC driver, or a mismatched SSL configuration.

The goal of this guide is to isolate whether the failure exists at the network layer, the driver layer, or the authentication layer to avoid wasting time changing credentials when the issue is actually a blocked port.

Diagnostic Signal Table

Error Signal	Likely Root Cause	Diagnostic Layer
Connection timed out / Connection refused	Wrong host/port or Firewall/Security Group block	Network
No suitable driver found / ClassNotFoundException	Missing or incompatible JDBC driver	Driver
Access denied / Authentication failed	Wrong credentials or missing IAM permissions	Authentication
SSL handshake failed / PKIX path building failed	Certificate mismatch or SSL mode conflict	Security/SSL

Step-by-Step Connection Troubleshooting

1. Isolate the Network Path

Before adjusting DBeaver settings, verify that the database server is reachable from your local machine. This separates DBeaver's configuration from infrastructure issues.

Run a connectivity check from your terminal (Command Prompt or Bash) using the same host and port configured in DBeaver:

# Example for a PostgreSQL database on port 5432
# Run this on your local workstation
nc -zv [your-db-host] 5432
# OR on Windows
Test-NetConnection -ComputerName [your-db-host] -Port 5432

• If this fails: The issue is external to DBeaver. Check your VPN, server security groups, or local firewall.
• If this succeeds: The network path is open; proceed to driver and authentication checks.

2. Verify JDBC Driver Compatibility

DBeaver uses JDBC (Java Database Connectivity) drivers to communicate with databases. A version mismatch between the driver and the server can cause the connection to hang or fail during metadata retrieval.

1. Right-click your connection in the Database Navigator and select Edit Connection.
2. Click Driver Settings.
3. Check the Libraries tab. Ensure the driver version matches the major version of your database server (e.g., using a PostgreSQL 15 driver for a PostgreSQL 15 server).
4. If the driver is missing or outdated, click Download/Update to fetch the latest version from the DBeaver repository.

3. Resolve SSL and Certificate Mismatches

SSL failures occur when the server requires encryption but the client is not configured for it, or when the client cannot verify the server's certificate (PKIX errors).

Decision Matrix for SSL:

• Server requires SSL, Client is off: The connection will abort during the handshake. Set SSL Mode to require or verify-ca in the SSL tab.
• Server does not support SSL, Client is on: The server will reject the encrypted request. Set SSL Mode to disable.
• Self-signed certificates: If using a private CA, you must provide the Root Certificate file path in the SSL settings to avoid PKIX path building errors.

4. Validate Authentication and IAM

If the network and SSL are correct but you receive "Access Denied," verify the authentication method.

• Standard Auth: Confirm the username and password. Ensure the user has permissions to connect from your specific IP address.
• Cloud IAM (AWS/Azure/GCP): Managed databases often require specific driver properties. In the Driver Properties tab, look for keys like sslmode or plugin_auth that may need to be set to iam or azure.

Verification and Rollback

To verify the fix, use the Test Connection button in the Connection Settings dialog. Do not rely solely on the Database Navigator tree, as it may cache old failure states.

Rollback Procedure: Since connection settings are stored in the DBeaver configuration files (XML), the only state change is the modification of these parameters. To rollback, manually revert the specific property (e.g., change SSL Mode back to disable) or restore a backup of your connections.json file if you have one.

When to Escalate

If the connection succeeds via a native command-line client (e.g., psql or sqlcmd) on the same machine but fails in DBeaver despite correct driver and SSL settings, collect the following before escalating to your DBA or DBeaver support:

• DBeaver Log: Go to Help > Log and copy the stack trace associated with the failure.
• Environment Details: DBeaver version (Community/Enterprise), OS, and the exact JDBC driver version used.
• Redacted Connection String: Provide the host and port, but redact all passwords and usernames.