quarkusio/quarkus · error · IllegalStateException

Invalid JKS key store configuration for certificate '" + nam

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.

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)

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.