Diagnosing DBeaver SSH Tunnel Failures: A Step‑by‑Step Guide

Recognizable Condition

In DBeaver the connection test either hangs indefinitely, times out after the configured timeout, or shows an error such as Failed to create SSH tunnel. The key clue is that a direct database connection from the same host (without the SSH tunnel) succeeds.

Cause & Diagnostic Table

Potential Cause	Typical Error Message	Why It Happens
Incorrect SSH host, port, or username	Connection timed out	DNS resolution fails or the SSH server is unreachable
Wrong private‑key path or missing key file	Failed to create SSH tunnel	DBeaver cannot load the key for authentication
Private‑key passphrase not supplied	Authentication failed	OpenSSH requires the passphrase to decrypt the key
Firewall blocks SSH port 22	Connection timed out	Network policy prevents outbound SSH traffic
Local tunnel port already in use	Failed to bind local port	Another process or DBeaver instance is using the same port
SSH server rejects authentication method	Authentication failed	Server is configured to accept only password or only public‑key

Ordered Checks

1. Verify SSH credentials from the OS

   # Replace placeholders with actual values
   ssh -i /path/to/private_key -p 22 username@ssh-host
   

   Success indicates the key and credentials are valid. A failure (e.g., “Permission denied” or “Connection timed out”) points to SSH‑level issues.

2. Inspect DBeaver SSH settings
   • Open the connection editor → SSH tab.
   • Confirm SSH host, SSH port, Username, and Private key file paths.
   • Check Authentication method (Password vs. Public key).
   • Verify the Local port is free (use netstat -tuln | grep :port on Linux).
3. Test database connection without the tunnel
   • In the same connection editor, disable the Use SSH tunnel checkbox.
   • Run Test Connection to confirm network reachability to the database host and port.
4. Check DBeaver log for tunnel errors
   • Open Window → Show View → Error Log (or Help → Show Log).
   • Look for stack traces containing SSH or tunnel keywords.

Fixes Tied to Findings

• Wrong host/port/username – correct the values in the SSH tab.
• Missing or mis‑located key – place the key in a readable location and update the Private key file field.
• Passphrase required – enable Use key passphrase and enter it (or use an agent like ssh‑agent).
• Firewall blocking port 22 – add a rule to allow outbound SSH or use a non‑standard port if the server permits.
• Local port conflict – change the Local port to an unused number or enable Auto‑assign local port if available.
• Authentication method mismatch – if the server allows only password, switch to Password in DBeaver; if only public‑key, ensure the key is correctly configured.

Escalation Criteria

If all the above checks pass but the tunnel still fails, gather the following before contacting support or your network team:

• DBeaver edition (Community vs. Enterprise) and exact version.
• Driver name and version used for the database.
• Exact error message from the connection test and from the OS ssh command.
• SSH server OS and SSH daemon version.
• Network topology: whether the client is inside a corporate VPN, behind NAT, or on a public IP.
• Contents of ~/.ssh/config if any custom host aliases are used.

Practical Checklist

# 1. Verify SSH from terminal
ssh -i /path/to/key -p 22 user@ssh-host

# 2. Confirm local port is free
netstat -tuln | grep :3307   # example local port

# 3. Test DB without tunnel
# (in DBeaver, uncheck SSH and run Test Connection)

# 4. Review DBeaver log for tunnel errors
# (Window → Show View → Error Log)

Limitations & Caveats

• DBeaver Community Edition may lack certain SSH UI options that Enterprise Edition provides (e.g., “Use SSH agent”).
• Storing a key passphrase in the DBeaver connection file is insecure; use an SSH agent if policy permits.
• Concurrent DBeaver connections using the same local port will conflict; each connection should use a unique local port or the auto‑assign feature.
• Some cloud providers block outbound SSH from certain IP ranges; verify that the client IP is allowed.

Conclusion

By following the ordered checks and applying the targeted fixes, most DBeaver SSH tunnel failures can be resolved locally. When the problem persists, the escalation bundle above will give support teams the data they need to dig deeper into server‑side or network‑level issues.