MySQL Workbench SSH Tunnel Fails: Quick Fix

I know the frustration. You're trying to connect to your remote MySQL database through SSH, and Workbench just sits there. Then it throws the "Lost connection to MySQL server" error after a timeout. It's annoying. But don't worry – I've seen this hundreds of times.

The most common cause (and the fix)

In 9 out of 10 cases, the problem is that MySQL Workbench uses a built-in SSH library that doesn't play nice with some server configurations. The fix is to tell Workbench to use an external SSH client instead. Here's exactly how to do it.

1. Close MySQL Workbench if it's open.
2. Open the MySQL Workbench configuration file. Where it lives depends on your OS:
   • Windows: C:\Users\YourUserName\AppData\Roaming\MySQL\Workbench\workbench_user_backend.xml
   • macOS: ~/Library/Application Support/MySQL/Workbench/workbench_user_backend.xml
   • Linux: ~/.mysql/workbench/workbench_user_backend.xml
3. Open that file in a text editor (Notepad works fine).
4. Look for the line that says <value type="int" key="sshtunnel:sshclient">0</value>. This number tells Workbench which SSH client to use. 0 = built-in, 1 = external.
5. Change the 0 to 1, so it reads: <value type="int" key="sshtunnel:sshclient">1</value>
6. Save the file and close it.
7. Restart MySQL Workbench.
8. Try your SSH tunnel connection again.

After this change, you should see the connection succeed within a few seconds. If it still fails, move to the next section.

Why this works

Workbench's built-in SSH library sometimes has issues with newer SSH servers that use diffie-hellman-group-exchange-sha256 key exchange or other modern ciphers. By switching to the external SSH client (which is OpenSSH on Mac/Linux, or Plink/PuTTY on Windows), you use the more robust SSH implementation that's already on your system. The external client handles key exchange better and doesn't timeout as quickly.

What if the SSH client is not found?

If you get an error saying "SSH client not found" after making the change, you need to tell Workbench where your SSH client lives. Here's how:

For Windows users

Workbench looks for plink.exe (from PuTTY) by default. If you don't have PuTTY installed, download it from putty.org. Install it. Then in the Workbench config file, look for a line like this:

<value type="string" key="sshtunnel:sshclientpath"></value>

Change it to the full path to plink.exe. For example:

<value type="string" key="sshtunnel:sshclientpath">C:\Program Files\PuTTY\plink.exe</value>

Save, restart Workbench, try again.

For Mac and Linux users

Workbench usually finds OpenSSH automatically (it's built into the OS). But if you're using a custom path, the config line is the same – just point it to your SSH binary (usually /usr/bin/ssh).

Less common causes that still happen

Your SSH key is the wrong format

Workbench only accepts private keys in PEM format. If you generated your key with PuTTYgen (it saves in .ppk format), that won't work directly. Convert it: in PuTTYgen, click "Conversions" → "Export OpenSSH key". Save that file and point Workbench to it in the connection settings.

The SSH server uses a non-standard port

I've seen people type the port in the wrong field. In Workbench's connection setup, under "SSH Hostname", you enter both the host and port like this: example.com:2222 (replace 2222 with your actual SSH port). If you put the port separately in the "SSH Port" field, that actually works too – but many people leave it blank and it defaults to 22, which fails if your server uses a different port.

Key-based auth but no password

If your server uses key authentication with an empty passphrase, Workbench sometimes gets confused. Try adding a passphrase to your key (even a short one) and see if that helps. I know it sounds backwards, but it does work sometimes.

How to prevent this from happening again

Once you've got the connection working, do these two things:

• Test the connection immediately after any Workbench update. Updates can reset the config file back to default (built-in SSH client). If you update and the tunnel breaks, check the config file first.
• Keep your SSH client up to date. On Windows, update PuTTY every few months. On Mac, run brew upgrade openssh if you use Homebrew. Old SSH clients can cause handshake failures.

That's it. The external SSH client fix solves this 90% of the time. If you're still stuck after trying all this, the problem might be on the server side – check the SSH server logs (usually in /var/log/auth.log or /var/log/secure) for error messages.