quarkusio/quarkus · error · IllegalStateException

Invalid JKS trust store configuration for certificate '" + n

Error message

Invalid JKS trust store configuration for certificate '" + name + "' - cannot read the trust store file '" + config.path() + "'

What it means

Quarkus TLS registry throws this IllegalStateException when building JksOptions for a configured JKS trust store fails because the trust store file could not be read (UncheckedIOException). It wraps the underlying IO error so the startup fails fast with the certificate name and configured path in the message.

Source

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

    }

    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());
            }
        } 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) {

View on GitHub (pinned to e1c734241f)

Solutions

Verify the path in quarkus.tls.<name>.trust-store.jks.path is correct and the file exists at runtime (use an absolute path to rule out working-directory differences).
Check file permissions so the user running Quarkus can read the file (chmod/chown).
In containers/Kubernetes, confirm the secret/configmap volume containing the trust store is mounted before startup.
Confirm the file is a real JKS store; if it is PEM or PKCS#12, configure the matching store type instead.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

java.nio.file.Path p = java.nio.file.Path.of(path);
if (!java.nio.file.Files.isRegularFile(p) || !java.nio.file.Files.isReadable(p)) {
    throw new IllegalStateException("JKS trust store not readable: " + p.toAbsolutePath());
}

Try / catch

try {
    // application startup / TLS config usage
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("cannot read the trust store file")) {
        log.errorf(e, "Fix quarkus.tls.<name>.trust-store.jks.path; current file missing/unreadable");
    }
    throw e;
}

Prevention

Use absolute paths for keystore/truststore files in production config.
Mount trust stores via secrets/configmaps and verify mounts in container entrypoint.
Add a smoke check (Files.isReadable) before startup or in CI.
Keep store files with read permission for the runtime user only.

When it happens

Trigger: Configuring quarkus.tls.*.trust-store.jks with a path that does not exist, is a directory, or is unreadable; the call to read(config.path()) raising UncheckedIOException is caught in JKSTrustStoreConfig.toOptions (JKSKeyStores.java:97-99) during verifyJKSTrustStoreStore.

Common situations: Typo in quarkus.tls.<name>.trust-store.jks.path; file mounted after startup in containers; wrong relative path because working directory differs in dev vs prod; permissions denied for the app user; path points at a PKCS#12 file renamed .jks plus unrelated IO failures.

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/1e72c38111c78373. Report an issue: GitHub.