quarkusio/quarkus · error · IllegalStateException

Quarkus does not support Client Certificate based authentica

Error message

Quarkus does not support Client Certificate based authentication

What it means

Quarkus substitutes SQLServerCertificateUtils.getKeyManagerFromFile to throw IllegalStateException in native mode. Client certificate authentication (TLS client cert via PEM cert/key files) in the MSSQL driver relies on crypto code excluded from the native image, so it is explicitly rejected.

Source

Thrown at extensions/jdbc/jdbc-mssql/runtime/src/main/java/io/quarkus/jdbc/mssql/runtime/graal/com/microsoft/sqlserver/jdbc/SQLServerJDBCSubstitutions.java:56

    @Substitute
    private void setKeyVaultProvider(String keyStorePrincipalId, String keyStoreSecret) throws SQLServerException {
        throw new IllegalStateException("Quarkus does not support Keyvault-based column encryption");
    }

    @Substitute
    ArrayList<byte[]> initEnclaveParameters(SQLServerStatement statement, String userSql, String preparedTypeDefinitions,
            QuarkusSqlParameter[] params, ArrayList<String> parameterNames) throws SQLServerException {
        throw new IllegalStateException("Quarkus does not support AAS Enclave");
    }
}

@TargetClass(className = "com.microsoft.sqlserver.jdbc.SQLServerCertificateUtils")
final class QuarkusSqlSQLServerCertificateUtils {
    @Substitute
    static KeyManager[] getKeyManagerFromFile(String certPath, String keyPath, String keyPassword)
            throws IOException, GeneralSecurityException, SQLServerException {
        throw new IllegalStateException("Quarkus does not support Client Certificate based authentication");
    }
}

@TargetClass(className = "com.microsoft.sqlserver.jdbc.SQLServerLexer")
@Delete //Deleting this one explicitly, so to help with maintenance with the substitutions of SQLServerFMTQuery
final class SQLServerLexerRemove {

}

/**
 * This will make sure the ANTLR4 Lexer included in the driver is not reachable; this was mostly
 * prevented by not allowing to explicitly set the useFmtOnly connection property, but this code
 * path would also get activated on very old SQL Server versions being detected on a connection.
 * Since that's not a constant that the compiler can rely on, we need one more substitution.
 */
@TargetClass(className = "com.microsoft.sqlserver.jdbc.SQLServerFMTQuery")
final class SQLServerFMTQuery {

View on GitHub (pinned to e1c734241f)

Solutions

Remove clientCertificate/clientKey settings and authenticate via user/password or Kerberos
Convert the client certificate into a Java KeyStore and use standard SSL keystore configuration (javax.net.ssl.keyStore) if the driver path supports it in native
Terminate mTLS at a proxy/sidecar and connect to it plainly or with server-only TLS
Use JVM mode where client-certificate authentication works

Example fix

// before
String url = "jdbc:sqlserver://host;database=db;clientCertificate=/certs/client.pem;clientKey=/certs/client.key";
// after
String url = "jdbc:sqlserver://host;database=db;user=app;password=...";

Defensive patterns

Strategy: validation

Validate before calling

if (url.contains("clientCertificate=") || url.contains("clientKey=")) { throw new IllegalArgumentException("Client certificate auth is not supported in native mode"); }

Type guard

static boolean usesClientCertAuth(String url) { return url != null && (url.contains("clientCertificate=") || url.contains("clientKey=")); }

Try / catch

try { conn = ds.getConnection(); } catch (IllegalStateException e) { if (e.getMessage().contains("Client Certificate")) { log.error("Use SQL/Kerberos auth instead of client certs in native mode"); } throw e; }

Prevention

Avoid clientCertificate/clientKey URL params in native configs
Terminate mTLS at a proxy when native support is required
Standardize on SQL or Kerberos authentication for native builds
Verify certificate-based auth in a native smoke test before rollout

When it happens

Trigger: Native-mode connection configured with clientCertificate / clientKey (PEM files) for client certificate authentication to SQL Server, reaching getKeyManagerFromFile(certPath, keyPath, keyPassword).

Common situations: Mutual TLS setups using client certs; connection strings copied from containers/services that authenticate with client certificates; hardening configurations requiring cert-based auth.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/3d5b0e189e32e00d. Report an issue: GitHub.