You type mysql -u app -p, get a prompt, then paste the same password into HeidiSQL, Workbench, Sequel Ace, or TablePlus and the login dies on caching_sha2_password. On MySQL 8 and newer that split is common. The official CLI bundles the client plugin. Many desktop connectors still speak only mysql_native_password. A Unix socket login is also not the same handshake as TCP to 127.0.0.1 on port 3306.
Read the exact error before you change the user
Workbench, DBeaver, HeidiSQL, Sequel Ace, and phpMyAdmin wrap the same server messages. Copy the code first. The text decides whether you upgrade the GUI or fix a transport setting.
| Message | What it means |
|---|---|
| Error 2059, plugin cannot be loaded, or "authentication method unknown to the client" | The connector does not implement caching_sha2_password. |
| Error 2061, "Authentication requires secure connection" | The GUI knows the plugin, but this TCP session needs TLS or RSA public-key exchange. |
| Error 1045, Access denied | Wrong password, or a different user@host than the CLI used. |
Treat 2059 or 2061 as the working diagnosis until the rows above are ruled out. Changing the account plugin will not fix a mistyped password, and it will not help a MySQL 9 server that no longer ships mysql_native_password.
Confirm the plugin and the host from the working CLI
Use the session that already works. Guessing in the GUI hides the host part of the account name.
- Run
SELECT USER(), CURRENT_USER();.USER()is how you connected.CURRENT_USER()is the matching grant row. - Run
SELECT user, host, plugin FROM mysql.user WHERE user = 'app';(swap the username). - Compare hosts. A socket login is
'app'@'localhost'. A GUI field set to127.0.0.1authenticates as'app'@'127.0.0.1'or'app'@'%'. Those rows can use different plugins. - Repeat the CLI over TCP:
mysql -h 127.0.0.1 -P 3306 -u app -p. - If step 4 fails with 2061 while step 1 succeeded, the password is fine. The cache and the transport are not.
Docker adds a second trap: docker exec uses the socket inside the container. Your GUI talks to the published host port. Fix mapping in Connect a MySQL GUI to Docker, then come back here for the plugin.
Why the CLI can succeed while TCP fails
caching_sha2_password keeps an in-memory cache per account. A first connection after CREATE USER, ALTER USER ... IDENTIFIED BY, FLUSH PRIVILEGES, or a server restart must complete full authentication. Full auth over Unix socket or shared memory is treated as a secure channel, so the password can ride that channel. Full auth over plain TCP needs TLS, or the client must fetch the server RSA public key (mysql --get-server-public-key on the CLI). JDBC-based tools such as DBeaver expose this as allow public key retrieval. Skip that for production internet hosts. Use it only on local or tunneled TCP.
After one successful full auth, later TCP logins may use the cache and succeed until the cache is cleared. That is why a GUI can start working after you logged in from Terminal, then fail again after a restart. The CLI did not repair the GUI. It warmed the cache.
Windows named pipes follow the unencrypted path, so they need RSA as well. macOS Homebrew and Linux packages default to a socket under /tmp/mysql.sock or /var/run/mysqld/mysqld.sock. Your GUI almost never uses that file unless you point it at the socket on purpose.
Fix the client, not the default plugin
For 2059, update the desktop client or pick one built on a MySQL 8 connector. Old HeidiSQL builds, old Connector/J 5.1 stacks, PHP mysqli from the 7.2 era, and stale Workbench copies are the usual sources. Current DBeaver, current Workbench, TablePlus, and TabulaSQL all speak the plugin. Check SELECT VERSION(); after you connect so you know you hit MySQL 8.4 or 9.x, not a leftover 5.7.
mysql_native_password is the workaround you will still find in old forum threads:
ALTER USER 'app'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'the-same-password';
Use that only on MySQL 8.0 when you cannot replace the GUI today. The plugin is deprecated as of 8.0.34, disabled by default in 8.4, and removed in 9.0. TabulaSQL is tested against MySQL 8.4 and MySQL 9.7, where weakening the account is the wrong direction. default_authentication_plugin in my.cnf or my.ini affects new accounts only. Existing users keep the plugin stored in mysql.user.
Do not open port 3306 to the internet to make the GUI work. If the server is remote, tunnel it. The SSH tunnel guide covers that path. The plugin still has to match once the tunnel lands on localhost TCP.
Use a GUI that already targets MySQL 8.4
If you want a free desktop client developed against MySQL 8.4, MySQL 9.7, and MariaDB 11, try TabulaSQL. Credentials stay encrypted on your machine. There is no cloud account and no telemetry.
- Add a MySQL/MariaDB connection and set host
127.0.0.1(or the Docker published host), port 3306 unless you remapped it, userapp, and the password that already works in the CLI. - Leave SSH off for a local server. For a remote host, fill the SSH tunnel fields instead of exposing 3306.
- Click Test connection. Save only after it succeeds, then run
SELECT VERSION(), CURRENT_USER();in the editor (Ctrl+Enter, or Cmd+Enter on Mac).
MariaDB does not use caching_sha2_password the way MySQL 8 does. If the GUI error names that plugin, you are talking to a MySQL server, not MariaDB, even if the port looks local. For Homebrew socket confusion on a Mac, see How to connect to MySQL on Mac. Turn Safe Lock on if you then edit rows on a shared server.