Diagnosing DBeaver Connection Timeouts and Authentication Failures

Recognizable Condition

While using DBeaver you hit "Connection timed out" or "Authentication failed" when clicking Test Connection or opening a SQL editor. The UI shows a red error icon and a brief message, but no details on why the connection was rejected.

Common Causes & Quick Reference Table

Issue	Typical Symptom	Root Cause
Timeout	"Timed out after X ms"	Network latency, firewall blocking port, incorrect host/port in JDBC URL
Authentication Failure	"Login failed for user"	Wrong username/password, expired password, insufficient DB privileges
Driver Mismatch	ClassNotFoundException or Unsupported JDBC version	Driver not compatible with DB version or DBeaver build
Idle Session Drop	Connection silently closed after idle period	Server enforces session limits or max connections

Diagnostic Checklist

1. Verify Network Reachability
   

   # From the machine running DBeaver
   ping -c 4 db-host.example.com
   # or
   nc -vz db-host.example.com 5432
   

   • Expected: reply packets or "succeeded" message.
   • Risk: A blocked port may return a timeout; check firewall settings.
2. Confirm JDBC URL Syntax
   

   jdbc:postgresql://db-host.example.com:5432/mydb?sslmode=require
   

   • Check vendor docs for exact format.
   • Common mistakes: missing colon after protocol, wrong port, typos in parameter names.
3. Inspect DBeaver Error Log
   
   • In DBeaver: Help → Show Log or View → Error Log.
   • Look for stack traces mentioning java.net.SocketTimeoutException or AuthenticationFailedException.
4. Cross‑Check Server Logs
   
   • On the database host, inspect pg_log (PostgreSQL) or error.log (MySQL) for connection attempts.
   • Search for entries matching the client IP or username used in DBeaver.
5. Validate Credentials & Privileges
   

   # Use a CLI client to test the same credentials
   psql -h db-host.example.com -U myuser -d mydb -p 5432
   

   • If the CLI fails, credentials or privileges are the problem.
6. Check Driver Compatibility
   
   • In DBeaver: Database → Driver Manager, verify the driver class and jar version.
   • Download the latest driver from the vendor if mismatched.

Fixes Tied to Findings

• Network/Firewall Issues
  
  • Open the required port (e.g., 5432 for PostgreSQL) on the firewall.
  • Use telnet db-host.example.com 5432 to confirm connectivity from the DBeaver host.
• Incorrect JDBC URL
  
  • Correct the host, port, and parameter list. Example for MySQL:
    

    jdbc:mysql://db-host.example.com:3306/mydb?useSSL=false&serverTimezone=UTC

• Authentication Problems
  
  • Reset the password on the database side and update DBeaver’s credential store.
  • Ensure the user has the required CONNECT privilege on the database.
  • For Windows authentication, verify that the JDBC driver supports it and that the integratedSecurity=true parameter is set.
• Driver Mismatch
  
  • Remove the old driver jar from DBeaver’s driver manager.
  • Import the correct jar (e.g., postgresql-42.6.0.jar for PostgreSQL 15) and set the driver class accordingly.
• Idle Session Limits
  
  • Adjust the server’s idle_in_transaction_session_timeout (PostgreSQL) or wait_timeout (MySQL) to a higher value.
  • Alternatively, enable DBeaver’s Keep‑alive setting in the connection properties.

Escalation Criteria

1. If the network test (ping/telnet) succeeds but DBeaver still times out, suspect a SSL/TLS mismatch. Verify that the server’s certificate is trusted by the client’s JVM truststore.
2. If the server logs show authentication failures, but the CLI client works, check for Kerberos/SPNEGO or other domain‑specific authentication mechanisms that DBeaver may not support out of the box.
3. If driver errors persist after updating the jar, confirm that the DBeaver version supports the JDBC driver’s API level. Consider upgrading DBeaver or downgrading the driver.
4. When all local checks pass but the connection still fails, contact the database administrator to review firewall rules, server load, or global connection limits.

Practical Example: PostgreSQL Timeout Fix

Scenario: DBeaver shows Timed out after 15000 ms when connecting to a remote PostgreSQL instance.

1. Run nc -vz db.example.com 5432 → returns succeeded.
2. Check DBeaver JDBC URL: jdbc:postgresql://db.example.com:5432/mydb – correct.
3. Review server logs: FATAL: connection to database “mydb” failed: timeout – indicates server side timeout.
4. Increase tcp_keepalives_idle on the PostgreSQL server or enable keepalive=1 in the JDBC URL.
5. Test connection again → success.

Verification Checklist

• Ping/Telnet from DBeaver host succeeds.
• DBeaver’s Test Connection shows Connection successful.
• No timeout or authentication errors appear in the logs.
• Server logs confirm the connection attempt and show no rejection.

Limitations & Notes

• Adjusting timeout settings can mask underlying network problems; always run the diagnostics first.
• SSL/TLS issues may require importing certificates into the JVM truststore; this is beyond the scope of DBeaver’s GUI.
• Some databases enforce strict IP whitelisting; ensure the DBeaver host’s IP is allowed.