quarkusio/quarkus · error · java.lang.IllegalStateException

Unable to load JKS ${type} store '${name}', verify the passw

Error message

Unable to load JKS ${type} store '${name}', verify the password.

What it means

Thrown by JKSKeyStores.loadKeyStore when loading a JKS/JCEKS-style store fails with a password error: the KeyStore.load call cannot unlock the store file, almost always because the configured password is wrong (or the store is corrupted and fails integrity checks the same way). The catch for the password-related failure rethrows with this message prompting a password check, naming the store type and configuration name.

Source

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

    private static void verifyTrustStoreAlias(JksOptions options, String name, KeyStore ks) {
        String alias = options.getAlias();
        if (alias != null) {
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS trust store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS trust store '" + name + "'", e);
            }
        }
    }

    private static KeyStore loadKeyStore(Vertx vertx, String name, JksOptions options, String type) {
        try {
            return options.loadKeyStore(vertx);
        } catch (Exception e) {
            throw new IllegalStateException("Unable to load JKS " + type + " store '" + name + "', verify the password.", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

  1. Verify the key store password matches the one used to create the store (keytool -list -keystore path)
  2. Check that the configured path resolves and points to a real JKS/PKCS12 file
  3. Recreate the store if corrupt: keytool -genkeypair -keystore ks.jks
  4. If credentials come from a credential provider, verify the provider returns the right password

Example fix

// before
quarkus.tls.key-store.jks.path=certs/ks.jks
quarkus.tls.key-store.jks.password=secret1
// after
quarkus.tls.key-store.jks.path=certs/ks.jks
quarkus.tls.key-store.jks.password=correct-password
Defensive patterns

Strategy: validation

Validate before calling

// before startup
boolean ok = new JksOptions().setPath(path).setPassword(pwd) != null;
try (var in = java.nio.file.Files.newInputStream(java.nio.file.Path.of(path))) {
    var ks = java.security.KeyStore.getInstance("JKS");
    ks.load(in, pwd.toCharArray()); // fails fast with a clear cause
}

Try / catch

try { startApp(); } catch (IllegalStateException e) {
    if (e.getMessage().contains("Unable to load JKS")) { log.error("Check keystore path/password", e.getCause()); }
    throw e;
}

Prevention

When it happens

Trigger: options.loadKeyStore(vertx) throws for a key store configured via quarkus.tls.key-store.jks/p12 (wrong password, wrong path, corrupt file, wrong type).

Common situations: Password set with special chars not resolved correctly; keystore re-generated with a different password; file truncated or not actually a JKS file; case-sensitive path typo.

Related errors

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