DEV Community

Gowri Shankar Balasubramaniam
Gowri Shankar Balasubramaniam

Posted on

Fixing MariaDB ERROR 2002 (HY000): TLS Handshake Fails with “Host Is Not Allowed to Connect”

#database #networking #security #tutorial

If you administer MariaDB in a secured environment, you may encounter the following confusing error while connecting from a remote host:

ERROR 2002 (HY000): Received error packet before completion of TLS handshake.
The authenticity of the following error cannot be verified:
1130 - Host '192.168.0.100' is not allowed to connect to this MariaDB server
Enter fullscreen mode Exit fullscreen mode

At first glance, this looks like a TLS/SSL issue, but the root cause is often host-based access control, not encryption. This article explains why this happens, how TLS complicates the error message, and how to fix it securely.

Why This Error Is Misleading

The error appears during the TLS handshake phase, which causes MariaDB to suppress full reveal of server-side details. As a result:

  • MariaDB detects that the client host is not authorized
  • But TLS prevents full error verification
  • You receive a generic ERROR 2002 instead of a clean access-denied message

In short:

TLS is not broken authorization is.

Common Scenarios Where This Happens

This issue is frequently seen in environments with:

  • Enforced require_secure_transport=ON
  • TLS-enabled clients (--ssl / --ssl-mode=REQUIRED)
  • Remote application servers or containers
  • Hardened MariaDB installations (PCI DSS / SOC 2 aligned)

Typical causes include:

  • The client host IP is missing in mysql.user
  • The user exists only for localhost
  • Firewall or bind-address is not the issue (often misdiagnosed)

Step 1: Confirm the Server Is Reachable

From the client host (192.168.0.100):

nc -vz mariadb-server-ip 3306
Enter fullscreen mode Exit fullscreen mode

If this succeeds, networking is not the problem.

Step 2: Inspect User Host Permissions (Critical Step)

Log in locally to the MariaDB server:

sudo mariadb
Enter fullscreen mode Exit fullscreen mode

Check allowed hosts for the user:

SELECT User, Host FROM mysql.user WHERE User = 'appuser';
Enter fullscreen mode Exit fullscreen mode

Typical problematic output

+---------+-----------+
| User    | Host      |
+---------+-----------+
| appuser | localhost |
+---------+-----------+
Enter fullscreen mode Exit fullscreen mode

This means remote connections are explicitly denied, regardless of TLS.

Step 3: Grant Access to the Correct Host

Option A: Allow a specific IP (recommended)

CREATE USER 'appuser'@'192.168.0.100'
IDENTIFIED BY 'StrongPassword'
REQUIRE SSL;

GRANT ALL PRIVILEGES ON appdb.* TO 'appuser'@'192.168.0.100';
FLUSH PRIVILEGES;
Enter fullscreen mode Exit fullscreen mode

Option B: Allow a subnet (controlled environments)

CREATE USER 'appuser'@'192.168.0.%'
IDENTIFIED BY 'StrongPassword'
REQUIRE SSL;
Enter fullscreen mode Exit fullscreen mode

⚠️ Avoid '%' unless strictly required.

⚠️ You may also use the local domain name instead of the IP address when creating the database user.

Step 4: Verify TLS Configuration

Check server TLS settings:

SHOW VARIABLES LIKE 'require_secure_transport';
SHOW VARIABLES LIKE 'ssl_%';
Enter fullscreen mode Exit fullscreen mode

Expected secure configuration:

require_secure_transport = ON
ssl_ca   = /etc/mysql/ca.pem
ssl_cert = /etc/mysql/server-cert.pem
ssl_key  = /etc/mysql/server-key.pem
Enter fullscreen mode Exit fullscreen mode

Step 5: Test Connection Explicitly with TLS

From the client:

mariadb \
  -h mariadb-server-ip \
  -u appuser \
  -p \
  --ssl-mode=REQUIRED
Enter fullscreen mode Exit fullscreen mode

If the host permission is fixed, the TLS handshake will complete successfully.

Why MariaDB Throws ERROR 2002 Instead of ERROR 1130

Under non-TLS connections, you would normally see:
Enter fullscreen mode Exit fullscreen mode

ERROR 1130 (HY000): Host 'x.x.x.x' is not allowed to connect

But when TLS is enforced:

  • The server aborts early
  • Detailed authentication errors are hidden
  • MariaDB returns ERROR 2002 as a generic failure

This is expected behavior in hardened setups.

Security Best Practices (Strongly Recommended)

✔ Use host-specific users, not %
✔ Enforce REQUIRE SSL
✔ Keep require_secure_transport=ON
✔ Rotate credentials after permission changes
✔ Log connection errors via log_error_verbosity=3

These align well with PCI DSS, SOC 2, and zero-trust principles.

Conclusion

This error is not a TLS failure, it is an access control failure masked by TLS.

Once the correct host-based user permission is added, the error disappears immediately.

Top comments (0)