quarkusio/quarkus · error · java.lang.IllegalStateException

Unable to verify alias '${alias}' in JKS key store '${name}'

Error message

Unable to verify alias '${alias}' in JKS key store '${name}'

What it means

While verifying the configured alias in a JKS key store, KeyStore.getCertificate(alias) threw KeyStoreException (keystore not loaded / not initialized). Quarkus wraps it in this IllegalStateException.

Source

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

                    + "' - 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) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS key store '" + name + "'", e);
            }

            char[] ap = null;
            if (aliasPassword != null) {
                ap = aliasPassword.toCharArray();
            }

            try {
                if (ks.getKey(alias, ap) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS key store (private key not found)'" + name + "'");
                }
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS key store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException | NoSuchAlgorithmException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS key store '" + name + "'", e);

View on GitHub (pinned to e1c734241f)

Solutions

  1. Check the cause of the IllegalStateException for the underlying KeyStoreException detail.
  2. Remove custom KeyStore wrapping/providers and retest with the default JKS provider.
  3. Verify the store loads correctly with keytool -list using the same JDK/provider.
Defensive patterns

Strategy: try-catch

Validate before calling

try {
    KeyStore ks = KeyStore.getInstance("JKS");
    try (var in = java.nio.file.Files.newInputStream(java.nio.file.Path.of(keystorePath))) {
        ks.load(in, storePassword.toCharArray());
    }
    ks.getCertificate(alias);
} catch (java.security.KeyStoreException e) {
    throw new IllegalStateException("Keystore unusable before Quarkus verification: " + e.getMessage(), e);
}

Try / catch

try {
    // startup
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to verify alias")) {
        log.errorf(e.getCause(), "KeyStoreException while verifying alias %s", alias);
    }
    throw e;
}

Prevention

When it happens

Trigger: verifyKeyStoreAlias (JKSKeyStores.java:116-117) during verifyJKSKeyStore when the KeyStore instance is in an unusable state — rare, typically indicates an internal loading failure or exotic provider returning an uninitialized keystore.

Common situations: Custom SecurityProvider or keystore implementation returning a not-initialized KeyStore; classloading/provider issues in native mode; bugs introduced by wrapping the loaded keystore.

Related errors

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