quarkusio/quarkus · error · IllegalStateException

Invalid JKS key store configuration for certificate '" + nam

Error message

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

What it means

Catch-all wrapper in JKSKeyStores.toOptions for a key store: any exception other than UncheckedIOException (e.g. password problems wrapped elsewhere, I/O errors, malformed options) becomes this IllegalStateException naming the certificate. It masks the concrete failure, so the chained cause is essential.

Source

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

            String p = CredentialProviders.getKeyStorePassword(config.password(), keyStoreCredentialProviderConfig)
                    .orElse(null);
            if (p == null) {
                throw new IllegalArgumentException("Invalid JKS key store configuration for certificate '" + name
                        + "' - the key store password is not set and cannot be retrieved from the credential provider.");
            }
            options.setPassword(p);
            if (config.alias().isPresent()) {
                options.setAlias(config.alias().get());
            }
            String ap = CredentialProviders.getAliasPassword(config.aliasPassword(), keyStoreCredentialProviderConfig)
                    .orElse(null);
            options.setAliasPassword(ap);
            return options;
        } catch (UncheckedIOException e) {
            throw new IllegalStateException("Invalid JKS key store configuration for certificate '" + name
                    + "' - cannot read the key store file '" + config.path() + "'", e);
        } catch (Exception e) {
            throw new IllegalStateException("Invalid JKS key store configuration for certificate '" + name + "'", e);
        }
    }

    private static JksOptions toOptions(JKSTrustStoreConfig config,
            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());
            }

View on GitHub (pinned to e1c734241f)

Solutions

Inspect the cause chain (e.getCause()) logged by Quarkus for the root error
Fix the underlying issue indicated by the cause (password, path, provider)
Validate the JKS file with keytool -list -keystore keystore.jks
Simplify config to a minimal working case and add settings back incrementally

Example fix

# before (provider misconfigured -> wrapped error)
quarkus.tls.my-tls.key-store.jks.path=ks.jks
quarkus.tls.my-tls.key-store.jks.credentials-provider.name=typo
# after
quarkus.tls.my-tls.key-store.jks.path=ks.jks
quarkus.tls.my-tls.key-store.jks.credentials-provider.name=main

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate JKS file integrity before deployment
try (InputStream in = Files.newInputStream(Path.of(jksPath))) {
    KeyStore.getInstance("JKS").load(in, null);
} catch (Exception e) {
    throw new IllegalStateException("Validate with: keytool -list -keystore " + jksPath);
}

Try / catch

try {
    Quarkus.run(args);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid JKS key store configuration")) {
        Throwable root = e;
        while (root.getCause() != null) root = root.getCause();
        log.errorf("JKS config invalid, root cause: %s", root.toString());
    }
    throw e;
}

Prevention

Always inspect the cause chain for the real error
Validate keystores with keytool -list before shipping
Change one TLS config setting at a time and retest

When it happens

Trigger: Any non-file-read failure while converting quarkus.tls.<name>.key-store.jks config to Vert.x JksOptions — e.g. RuntimeException from credential provider lookup, null path handling, or unexpected parser errors.

Common situations: Misconfigured credentials-provider causing a nested failure; corrupted JKS file failing outside the read step; regressions after upgrading the TLS registry internals.

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/5166db13ba35beed. Report an issue: GitHub.