HeadlinesBriefing favicon HeadlinesBriefing.com

Fixing MariaDB ERROR 2002 TLS Handshake Failure

DEV Community •
×

A confusing ERROR 2002 during MariaDB connections often masks a simple host permission issue. When TLS is enforced, the server aborts the handshake early, hiding the true ERROR 1130 that the client host is not authorized. This leads developers to mistakenly diagnose a TLS problem instead of an access control failure.

This typically occurs in hardened environments with `require_secure_transport=ON`. The solution isn't tweaking TLS certificates but correcting the mysql.user table. Administrators must grant remote access to the specific client IP, using `CREATE USER 'appuser'@'client-ip' REQUIRE SSL` and then `GRANT` privileges, ensuring the user isn't restricted solely to localhost.

After fixing the user permissions, verify the connection using `mariadb --ssl-mode=REQUIRED`. This confirms the TLS handshake completes successfully once the host is authorized. The behavior is expected in secure setups, aligning with PCI DSS and zero-trust principles where detailed authentication errors are suppressed to avoid information leakage.