quarkusio/quarkus · error · java.lang.IllegalStateException

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

Error message

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

What it means

Thrown by JKSKeyStores.verifyTrustStoreAlias when checking the configured alias in a JKS trust store raises a KeyStoreException or NoSuchAlgorithmException. The alias lookup ks.getCertificate(alias) can fail for store-level reasons (uninitialized or corrupt store) independent of whether the alias exists; those checked exceptions are caught and rethrown as this IllegalStateException with the store name and original cause, distinguishing infrastructure failure from the 'alias not found' case.

Source

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

            } catch (KeyStoreException | NoSuchAlgorithmException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS key store '" + name + "'", e);
            } catch (UnrecoverableKeyException e) {
                throw new IllegalArgumentException(
                        "Unable to recover the key for alias '" + alias + "' in JKS key store '" + name + "'", e);
            }
        }
    }

    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. Inspect the wrapped cause for the underlying KeyStoreException.
  2. Validate the trust store with keytool -list to confirm it is not corrupted.
  3. Retest without custom security providers / with the default JDK JKS implementation.
Defensive patterns

Strategy: try-catch

Validate before calling

try {
    KeyStore ts = KeyStore.getInstance("JKS");
    try (var in = java.nio.file.Files.newInputStream(java.nio.file.Path.of(truststorePath))) {
        ts.load(in, storePassword.toCharArray());
    }
    ts.getCertificate(alias);
} catch (java.security.KeyStoreException e) {
    throw new IllegalStateException("Trust store unusable: " + e.getMessage(), e);
}

Try / catch

try {
    // startup
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("in JKS trust store")) {
        log.errorf(e.getCause(), "KeyStoreException verifying trust store alias %s", alias);
    }
    throw e;
}

Prevention

When it happens

Trigger: verifyTrustStoreAlias (JKSKeyStores.java:151-152) during verifyJKSTrustStoreStore when the loaded KeyStore instance is not in an operational state (uninitialized keystore or provider failure).

Common situations: Custom security provider issues; corrupted trust store causing the JKS implementation to fail; native-image provider registration problems.

Related errors

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