Why clientcert=verify-ca Breaks YSQL Connection Manager After Upgrading to 2025.1

Jim Knicely

If you use YSQL Connection Manager (YCM) and recently upgraded from YugabyteDB 2024.2 to 2025.1, you may have encountered a confusing failure:

  • Connections that previously worked through YCM suddenly stop working after the upgrade… even though your pg_hba.conf hasn’t changed.

In many cases, the root cause is an HBA rule that looks like this:

				
					hostssl all all all md5 clientcert=verify-ca

This tip explains why this rule “worked” in 2024.2, why it breaks in 2025.1, and what to do instead.

This behavior is closely related to two earlier YugabyteDB tips:

If you haven’t read those yet, they provide helpful background… especially around silently ignored HBA options.

The short version

  • ● YSQL Connection Manager does not support certificate-based authentication

  • ● In 2024.2, clientcert=verify-ca can be silently ignored

  • ● In 2025.1, clientcert=verify-ca is no longer ignored

  • ● Once enforced, that rule requires client certificates

  • ● YCM cannot satisfy that requirement → connections failure (Error: cert authentication is not supported with connection manager)

Nothing “regressed” in YCM… the rule simply started doing what it always claimed to do.

YSQL Connection Manager and certificate authentication

YSQL Connection Manager currently supports password-based authentication (for example, md5 or scram-sha-256).

It does not support certificate-based authentication, including:

  • ● cert auth method

  • ● Any HBA rule that requires client certificates via clientcert=verify-ca or clientcert=verify-full

This limitation is explicitly documented in the YCM documentation (Limitations)

As a result, any HBA rule that truly requires client certificate verification cannot work with YCM.

Notes:

  • ● YugabyteDB added scram-sha-256 support (for YCM) in 2024.2.4.0, so earlier 2024.2 builds may not support scram.
  • ● Refer to Authentication methods to view the various authentication methods supported by YugabyteDB and their compatibility with the YSQL Connection Manager.
Why this appeared to work on 2024.2

In YugabyteDB 2024.2, certain pg_hba.conf options, including
clientcert=verify-ca and clientcert=verify-full, can be accepted syntactically but ignored at runtime.

That means:

  • ● The rule parses successfully

  • ● No warning is logged

  • ● The rule still matches

  • ● Client certificate verification is not actually enforced

So on 2024.2, with YCM enabled:

  • ● The rule looks like it requires a client certificate

  • ● In reality, it behaves like plain md5

  • ● YSQL Connection Manager connections succeed

This is the same “silent ignore” behavior described in the earlier clientcert=verify-ca tip.

Important distinction: clientcert=1 never worked

This behavior is specific to the verify-ca / verify-full form.

If the same rule in 2024.2 had instead used the older PostgreSQL-style syntax:

				
					hostssl all all all md5 clientcert=1

YSQL Connection Manager would not have worked… even in 2024.2.

In that case:

  • ● The rule immediately requires client certificate authentication

  • ● The requirement is enforced

  • ● YCM cannot satisfy it

  • ● Connections fail with an error indicating cert-based auth is not supported

In short:

  • ● clientcert=1 → always enforced → YCM fails (all versions)

  • ● clientcert=verify-ca in 2024.2 → silently ignored → YCM works

  • ● clientcert=verify-ca in 2025.1 → enforced → YCM fails

The upgrade doesn’t change YCM behavior… it changes whether the HBA rule actually does what it says.

What changes in 2025.1

Starting in YugabyteDB 2025.1, clientcert=verify-ca is no longer ignored.

Once enforced:

  • ● The HBA rule genuinely requires a valid client certificate

  • ● PostgreSQL (i.e. YSQL) expects the client to present one

  • ● YSQL Connection Manager cannot do that

  • ● Connections through YCM fail

From the database’s point of view, this is correct behavior… the rule is now being honored.

How to confirm this is your issue
1. Confirm the session is using YSQL Connection Manager
				
					SHOW yb_is_client_ysqlconnmgr;

If this returns on, the session is using YCM.

2. Inspect how Yugabyte parsed your HBA rules
				
					SELECT * FROM pg_hba_file_rules ORDER BY line_number;

On 2024.2, you may see that clientcert=verify-ca does not appear in the parsed options column… a sign it was ignored.

On 2025.1, it will appear and be enforced.

3. Confirm which HBA rule matched

If you’ve implemented the helper function from the earlier “which rule matched” tip, use it to confirm exactly which rule is being applied to YCM connections.

This avoids guessing.

The fix

If clients connect through YSQL Connection Manager, their matching HBA rules must not require client certificates.

Recommended pattern for YCM clients

Use password-based authentication only:

				
					hostssl all appuser <app_subnet> scram-sha-256

or:

				
					hostssl all appuser <app_subnet> md5

Remove all clientcert=... options from any rule that could match YCM traffic.

What if you require client certificate verification?

If your security model requires client certificate verification:

  • ● You cannot use YSQL Connection Manager today

  • ● Those clients must connect directly to YSQL

  • ● YCM and cert-based auth are mutually exclusive (for now)

In practice, this usually means separating traffic by network path or address ranges, since HBA rules cannot match on port.

Is certificate-based authentication coming to YCM?

Yes, certificate-based authentication support for YSQL Connection Manager is planned and tracked in this public YugabyteDB GitHub issue: 20658… monitor it for progress and milestones.

Until that work is complete, any HBA rule that requires client certificate verification will not work with YSQL Connection Manager, regardless of YugabyteDB version.

Why this shows up during upgrades

This issue often appears only after upgrading, because:

  • ● The configuration appeared to work

  • ● The option was silently ignored in 2024.2

  • ● The upgrade makes the rule meaningful

  • ● YCM is suddenly unable to authenticate clients

Before upgrading to 2025.1 or later, review pg_hba.conf for:

  • ● clientcert=verify-ca

  • ● clientcert=verify-full

  • ● Any assumption that YCM supports certificate-based authentication

Summary

  • ● YSQL Connection Manager does not support certificate-based authentication

  • ● clientcert=1 never worked with YCM

  • ● clientcert=verify-ca may be ignored in 2024.2

  • ● In 2025.1, clientcert=verify-ca is enforced

  • ● Once enforced, YCM connections fail

  • ● Use password-based auth for YCM clients

  • ● Certificate support is planned but not yet available