Most Workbench connection failures are caused by one of four layers: the wrong VPS address or port, a MySQL listener that is local-only, a firewall or cloud security rule, or a MySQL account whose Host value does not match your workstation. Identify the error first, then test those layers in order. If the database does not need public exposure, an SSH tunnel is usually the safer path because MySQL can remain reachable only on the VPS itself.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
Choose the connection path before changing anything
MySQL Workbench offers two different ways to reach a server on a VPS. The choice determines which port, firewall rules and MySQL listener settings matter.
As an Amazon Associate I earn from qualifying purchases.
| Workbench method | What it does | Workbench fields | Typical network requirement | MySQL listener can remain on |
|---|---|---|---|---|
| Standard TCP/IP | Connects directly to the MySQL protocol over the network | MySQL hostname or IP, MySQL port, username and password | TCP 3306 (unless changed) must be reachable from your workstation through the VPS firewall and cloud security group | A VPS interface address, not only loopback |
| Standard TCP/IP over SSH | Creates an SSH tunnel to the VPS and sends the MySQL connection through it | SSH hostname, SSH port, SSH user, key or password, plus the MySQL-side host, port, username and password | SSH, normally TCP 22, must be reachable; MySQL only needs to be reachable from the VPS side of the tunnel | 127.0.0.1 or another private interface on the VPS |
The direct method is appropriate when a controlled network, private link or tightly restricted source rule can reach the database. The SSH method is useful when you do not want to expose port 3306 publicly. It also explains a common symptom: SSH tunneling works while direct TCP/IP fails. The tunnel is using a different route and can reach a MySQL listener that accepts local VPS connections only.
Classify the error before troubleshooting
The wording of the failure usually identifies the layer that stopped the connection. Do not start by changing MySQL grants if the workstation cannot reach the VPS, and do not keep adjusting firewall rules after MySQL has already returned an account error.
#1 Best Overall
| Symptom | Likely layer | First checks |
|---|---|---|
| DNS failure or timeout | Name resolution, route, firewall or cloud security group | Resolve the VPS name, verify the address is reachable from the workstation, test the selected port and inspect both firewall layers |
| Connection refused | No service is accepting that address and port, or the listener is bound elsewhere | Confirm mysqld is running, check skip_networking and inspect bind_address |
| Host not allowed | The TCP connection reached MySQL, but the account’s Host value does not match the client | Inspect the account’s user-and-host combination and create a suitably restricted host entry |
| Access denied | Credentials or privilege scope | Verify the username and password, then check grants for the required schema |
| Direct TCP/IP fails but SSH works | The direct exposure path, not necessarily MySQL itself | Keep the SSH method or correct the direct listener and firewall/security-group rules |
| SSH host-key warning | Known-host fingerprint verification | Confirm the VPS fingerprint through a separate trusted channel before accepting a changed key |
Use the VPS address, not an assumed localhost
For a direct connection
In the Standard TCP/IP profile, enter the VPS address that your workstation can actually reach. This might be a public address, a private-network address or a resolvable hostname. Use the MySQL listener port, which is 3306/TCP by default unless the server configuration changed it.
localhost in Workbench refers to the computer running Workbench, not automatically to the VPS. It can resolve to 127.0.0.1 or to ::1, the IPv6 loopback address. That sends the connection to a local listener, if one exists, and can also select a different MySQL account because MySQL matches accounts by both user and host.
For an SSH tunnel
Set the SSH hostname to the VPS address and supply the SSH port if it is not the normal port 22. Enter the SSH username and select the private key or password required by that account. In the MySQL portion of the profile, use the server-side listener address and port: commonly 127.0.0.1 and 3306 when MySQL is local-only. The MySQL host in this section is evaluated from the VPS side of the tunnel, not from your workstation’s public address.
Verify that mysqld is running and listening where you expect
Check the service state
A refused connection can simply mean that the MySQL service is stopped or failed during startup. On the VPS, inspect the service through your distribution’s service manager and review its error log if it is not running. Service names vary by distribution, so use the name installed on your system rather than assuming one universal label.
From a shell, a socket listing can show whether a process is listening on the expected port. For example, an administrator can use ss -ltnp | grep 3306 and compare the displayed local address with the address entered in Workbench. A listener on 127.0.0.1:3306 is local-only; a listener on a VPS interface address can accept traffic arriving on that interface, subject to firewall rules.
Inspect skip_networking
The skip_networking setting disables MySQL TCP/IP networking entirely. When it is enabled, a Workbench TCP/IP profile cannot connect even if the service is running and a firewall rule exists. Disable it only when network connections are required and your access controls are ready; otherwise use a local socket or an SSH design that matches the server’s available interfaces.
Recommended Free Tools
Inspect bind_address
The bind_address setting determines which local addresses accept TCP/IP connections. If it is set to 127.0.0.1, MySQL listens only on the loopback interface and does not accept remote TCP/IP connections. Direct Workbench access therefore fails by design.
To support direct access, bind MySQL to the specific VPS interface that should receive the connection, then restart or reload the service according to the server’s configuration procedure. A wildcard address listens on more interfaces and creates broader exposure; use it only when that scope is intentional. A specific IPv4 address is safer when the VPS has a known network interface for database traffic.
After changing the setting, verify the effective listener rather than relying only on the edited file. Configuration precedence can cause a later option or an included file to override the value you changed.
Check every firewall and security-group layer
Direct TCP/IP requires two network permissions
For a direct profile, TCP 3306 must be permitted both by the VPS operating-system firewall and by the hosting platform’s cloud firewall or security group. Allow the port only from the workstation’s actual source address, a controlled office range or a private network. Opening 3306 to every Internet address makes the database reachable for password attacks and scanning.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →If your workstation’s public address changes, a rule tied to the old address will produce a timeout even though MySQL and Workbench are configured correctly. Confirm the source address seen by the VPS and update the narrow rule when the network changes.
SSH tunneling needs SSH access, not public MySQL
For Standard TCP/IP over SSH, permit SSH (normally TCP 22) from the workstation to the VPS. Port 3306 does not need to be exposed to the Internet when the tunnel terminates on the VPS and MySQL is listening on a local or private address. The SSH account must also be allowed to log in and establish forwarding under the server’s SSH policy.
Interpret a timeout versus a refusal
A timeout commonly indicates a dropped packet, an incorrect address, a missing route or a firewall/security-group denial. A refusal generally means the address is reachable but no process is accepting that port, or a policy is actively rejecting it. Test the exact hostname and port selected in Workbench; testing a different address or port can lead to a false conclusion.
Fix MySQL account host matching and grants
Why the correct password can still fail
MySQL identifies an account by the combination of its user name and Host value. The account used from the VPS itself is not automatically the same account used from a workstation address. A login can therefore return “host is not allowed” or “access denied” even when the password is correct.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Determine the client host as MySQL sees it, then create or alter an account whose Host value matches that source. Examples include a single address such as 'appuser'@'198.51.100.25' or a constrained subnet appropriate to your network. Do not assume that the workstation’s private address is visible when the connection crosses a public NAT boundary.
Rank #4
Grant only the required schema
Give the account privileges on the needed database or schema, such as ON db_name.*, rather than administrative privileges for every database. A successful TCP connection followed by an error when opening a schema usually indicates a grant-scope problem, not a port problem.
Use wildcard hosts cautiously
An account with Host set to % can match connections from any host unless a more specific account wins. MySQL’s troubleshooting guidance warns that a broad wildcard can leave the account open to unwanted sources. Replace it with a specific address or tightly bounded subnet when the client location is known, and pair that restriction with an equally narrow firewall rule.
Free tools Windows power users keep installed
One-click scans. No signup required.
Configure Standard TCP/IP in Workbench
- Open the Workbench connection manager and create or edit a connection.
- Select Standard TCP/IP as the connection method.
- Enter the reachable VPS hostname or IP address. Do not use
localhostunless MySQL is running on the same computer as Workbench. - Enter the MySQL listener port, normally
3306unless the server was changed. - Enter the MySQL username and password for an account whose Host value permits this client.
- Save the profile, then run Workbench’s connection test.
- If the result is a timeout, return to address, route and firewall checks. If it is refused, inspect mysqld,
skip_networkingandbind_address. If MySQL returns an account error, inspect credentials, Host matching and grants.
Changing the Workbench port does not change the server’s listening port. Both sides must use the same effective port, and the firewall must allow that port.
Configure Standard TCP/IP over SSH in Workbench
- Open the connection manager and choose Standard TCP/IP over SSH.
- Set the SSH hostname to the VPS and enter its SSH port, normally
22. - Enter the SSH username that is permitted to log in to the VPS.
- Select the private key file or enter the SSH password required by that account.
- If Workbench asks about the SSH host fingerprint, compare it with a fingerprint obtained through a trusted, separate channel. A changed fingerprint should be investigated rather than blindly accepted.
- For the MySQL host, enter the address visible from the VPS, commonly
127.0.0.1when MySQL is bound to loopback. Enter the server-side MySQL port, normally3306. - Enter the MySQL username and password, then test the connection.
Workbench’s SSH method uses TCP/IP over an SSH connection; it does not turn an incorrect MySQL password into a valid one. The SSH login and the MySQL login are separate authentication steps.
Convert an incompatible private-key format
Workbench documents OpenSSH private-key input. If your key is in PuTTY’s .ppk format, convert it to an OpenSSH-compatible format before selecting it, or create an equivalent OpenSSH key according to your organization’s key-management policy.
Best Value
Why SSH works when direct TCP/IP does not
This result is usually expected when MySQL is intentionally private. The SSH client reaches the VPS on port 22, then forwards traffic from Workbench to a MySQL listener on the VPS’s loopback or private interface. A direct profile instead asks the network to deliver traffic to port 3306 on an address exposed to your workstation. If MySQL is bound to 127.0.0.1 or port 3306 is blocked by a security group, the direct route fails while the tunnel remains functional.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallYou have two valid choices: keep MySQL private and use the SSH profile, or deliberately enable direct access by binding to the required interface and restricting both firewall layers and MySQL account hosts. The second choice adds exposure and operational dependencies; it should be justified by a real need for direct network clients.
A safe decision framework: direct access or SSH?
| Decision factor | Direct TCP/IP | SSH tunnel |
|---|---|---|
| Internet exposure | Port 3306 is reachable wherever firewall rules permit it | Only SSH needs to be reachable; MySQL can stay private |
| Firewall complexity | Permit 3306 in the VPS firewall and cloud security group for approved sources | Permit SSH, normally 22, and keep the MySQL side reachable from the VPS |
| Listener setting | Must include the interface receiving remote traffic | Can remain on 127.0.0.1 or another VPS-private address |
| Account Host value | Must match the workstation or network source as seen by MySQL | Usually matches the VPS-side connection source, often local |
| Operational reachability | Convenient for approved applications and networks that need persistent direct access | Requires a working SSH login and tunnel for each session |
If your only requirement is administrative access from a workstation, SSH usually minimizes the number of exposed services. If several application hosts need database access over a private network, direct TCP/IP can be appropriate when the network, grants and monitoring are controlled.
Common mistakes and their corrections
- Using the workstation’s localhost: replace it with the reachable VPS address for a direct profile, or use 127.0.0.1 only in the MySQL section of an SSH profile when the server listens there.
- Opening a firewall port without a listener: a permitted port cannot help if mysqld is stopped,
skip_networkingis enabled orbind_addressis loopback-only. - Changing only Workbench’s port: match the server’s effective listener port and update both firewall layers.
- Granting
'user'@'localhost'for a remote client: add a host-specific account entry for the actual source instead of reusing a local-only account. - Using
'%'as a quick fix: replace the wildcard with a known address or subnet and restrict the firewall to the same scope. - Accepting a changed SSH fingerprint without checking: verify the VPS fingerprint out of band; a change can indicate reinstallation, key rotation or an interception attempt.
- Assuming a public address is always reachable from inside the VPS: for an SSH tunnel, use the MySQL address that the VPS can reach, commonly its loopback listener.
End-to-end troubleshooting checklist
- Record the exact Workbench error: timeout, refusal, host-not-allowed, access-denied or SSH fingerprint warning.
- Confirm whether the profile is Standard TCP/IP or Standard TCP/IP over SSH.
- Verify the hostname or IP and port in the profile. Use a reachable VPS address, 3306 for default MySQL or 22 for the SSH leg.
- On the VPS, confirm mysqld is running and inspect the actual listening sockets.
- Check that
skip_networkingis off when TCP/IP is required. - Check
bind_address; loopback-only binding rules out direct remote TCP/IP. - For direct access, permit TCP 3306 only from the approved source in both the VPS firewall and cloud security group.
- For SSH, permit SSH and keep the MySQL listener reachable from the VPS side of the tunnel.
- Verify the MySQL account’s Host value, username, password and schema-level grants.
- Retest after each layer changes so that a new error identifies the next layer rather than hiding several simultaneous problems.
When to stop exposing port 3306
If direct access requires a broad Internet firewall rule, a wildcard MySQL Host entry or a wildcard bind_address, reconsider the design. A private network path or SSH tunnel can meet the same administrative need with fewer publicly reachable components. Keep 3306 closed to the Internet when no external application requires it, and document the exact SSH account, key policy and MySQL local listener used by Workbench.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
