quarkusio/quarkus · error · IllegalStateException

Invalid JKS trust store configuration for certificate '" + n

Error message

Invalid JKS trust store configuration for certificate '" + name + "'

What it means

Generic fallback: when building JksOptions for a JKS trust store, any exception other than UncheckedIOException is wrapped into this IllegalStateException naming only the certificate. The cause holds the real problem (e.g. missing password, credential provider failure).

Source

Thrown at extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/keystores/JKSKeyStores.java:101

            TrustStoreCredentialProviderConfig trustStoreCredentialProviderConfig, String name) {
        JksOptions options = new JksOptions();
        try {
            options.setValue(Buffer.buffer(read(config.path())));
            String password = CredentialProviders.getTrustStorePassword(config.password(), trustStoreCredentialProviderConfig)
                    .orElse(null);
            if (password == null) {
                throw new IllegalStateException("Invalid JKS trust store configuration for certificate '" + name
                        + "' - the trust store password is not set and cannot be retrieved from the credential provider.");
            }
            options.setPassword(password);
            if (config.alias().isPresent()) {
                options.setAlias(config.alias().get());
            }
        } catch (UncheckedIOException e) {
            throw new IllegalStateException("Invalid JKS trust store configuration for certificate '" + name
                    + "' - cannot read the trust store file '" + config.path() + "'", e);
        } catch (Exception e) {
            throw new IllegalStateException("Invalid JKS trust store configuration for certificate '" + name + "'", e);
        }
        return options;
    }

    private static void verifyKeyStoreAlias(JksOptions options, String name, KeyStore ks) {
        String alias = options.getAlias();
        // Credential provider already called.
        String aliasPassword = options.getAliasPassword();
        if (alias != null) {
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS key store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS key store '" + name + "'", e);
            }

View on GitHub (pinned to e1c734241f)

Solutions

Read the cause (getCause()) of the IllegalStateException — the wrapper hides the real error.
Set quarkus.tls.<name>.trust-store.jks.password, or configure quarkus.tls.<name>.trust-store.credentials-provider.name so the password can be retrieved.
Validate the trust store config block for typos (password, alias, alias-password keys).

Example fix

// before
quarkus.tls.my-cert.trust-store.jks.path=/etc/quarkus/cacerts.jks
// after
quarkus.tls.my-cert.trust-store.jks.path=/etc/quarkus/cacerts.jks
quarkus.tls.my-cert.trust-store.jks.password=changeit

Defensive patterns

Strategy: try-catch

Validate before calling

if (configPassword == null && credentialProviderName == null) {
    throw new IllegalStateException("JKS trust store requires quarkus.tls.<name>.trust-store.jks.password or a credentials provider");
}

Try / catch

try {
    // startup
} catch (IllegalStateException e) {
    log.errorf(e, "JKS trust store config invalid; cause=%s", e.getCause());
    throw e;
}

Prevention

Always set trust-store.jks.password or a credentials provider name.
Always log/print e.getCause() for this generic wrapper.
Keep trust store config blocks minimal and validated in CI with a test profile startup.
Avoid dynamic password expressions that can fail silently.

When it happens

Trigger: During verifyJKSTrustStoreStore -> toOptions (JKSKeyStores.java:100-101) when reading the path, resolving the password via credential provider, or reading alias/aliasPassword throws a non-IO exception. Notably a missing trust store password throws this wrapper after the inner IllegalStateException is raised.

Common situations: quarkus.tls.<name>.trust-store.jks.password not set and no credential provider configured; credential provider bean misconfigured or unreachable; malformed config expression in password.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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