quarkusio/quarkus · error · IllegalStateException

Invalid JKS key store configuration for certificate '" +…

Error message

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

What it means

JKSKeyStores.toOptions reads the JKS key store file via read(config.path()); if that read throws UncheckedIOException (missing/unreadable file), it is rethrown as this IllegalStateException with the certificate name and path, chaining the original cause.

Solutions

Verify the path exists and is readable at runtime (absolute path recommended)
Package the JKS into the image (container COPY / native-image include) if containerized
Check the 'cause' UncheckedIOException for the exact filesystem error
Confirm the runtime user has read permission

Example fix

# before
quarkus.tls.my-tls.key-store.jks.path=keystore.jks
# after (absolute path inside container)
quarkus.tls.my-tls.key-store.jks.path=/opt/app/certs/keystore.jks

Defensive patterns

Strategy: validation

Validate before calling

Path ks = Path.of(cfg.getValue("quarkus.tls.my-tls.key-store.jks.path", String.class));
if (!Files.isReadable(ks)) throw new IllegalStateException("JKS keystore unreadable: " + ks.toAbsolutePath());

Try / catch

try {
    Quarkus.run(args);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("cannot read the key store file")) {
        log.errorf("JKS path bad; cause: %s", e.getCause());
    }
    throw e;
}

Prevention

Use absolute paths and verify readability at startup
Package keystores into the image explicitly
Check cause chain for the precise filesystem error

When it happens

Trigger: quarkus.tls.<name>.key-store.jks.path points at a nonexistent/unreadable file while building the key store options at startup.

Common situations: Typo in path; file not packaged into the container or native image; relative path resolved against a different working directory in prod; permissions denied for the runtime user.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

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/52aa90c0e3dba9b9. Report an issue: GitHub.

Appendix: source

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

        JksOptions options = new JksOptions();
        try {
            options.setValue(Buffer.buffer(read(config.path())));
            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);

View on GitHub (pinned to e1c734241f)