quarkusio/quarkus · error · java.lang.IllegalStateException

Alias '${alias}' not found in key store (certificate not fou

Error message

Alias '${alias}' not found in key store (certificate not found) '${name}'

What it means

The TLS registry verifies that a configured alias actually exists in the loaded key store during startup. This error means the key store loaded successfully, but no certificate is registered under the alias given via quarkus.tls.key-store.alias (or the per-certificate alias). It fails fast so misconfigured TLS does not surface only at first handshake.

Source

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

    private static KeyStore getInstance(String type, Optional<String> provider) {
        try {
            if (provider.isPresent()) {
                return KeyStore.getInstance(type, provider.get());
            }
            return KeyStore.getInstance(type);
        } catch (KeyStoreException | NoSuchProviderException e) {
            throw new IllegalStateException("Unable to create key store of type '" + type + "'"
                    + (provider.isPresent() ? " with provider '" + provider.get() + "'" : ""), e);
        }
    }

    private static void verifyKeyStoreAlias(OtherKeyStoreConfig config, String name, KeyStore ks,
            String aliasPassword) {
        if (config.alias().isPresent()) {
            String alias = config.alias().get();
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in key store (certificate not found) '" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in key store '" + name + "'", e);
            }

            char[] ap = aliasPassword != null ? aliasPassword.toCharArray() : null;
            try {
                if (ks.getKey(alias, ap) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in key store (private key not found) '" + name + "'");
                }
            } catch (KeyStoreException | NoSuchAlgorithmException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in key store '" + name + "'", e);
            } catch (UnrecoverableKeyException e) {
                throw new IllegalArgumentException(
                        "Unable to recover the key for alias '" + alias + "' in key store '" + name + "'", e);
            }

View on GitHub (pinned to e1c734241f)

Solutions

List the actual aliases with keytool -list -keystore <file> and set quarkus.tls.<name>.key-store.alias to an existing one
If you did not intend to restrict to one alias, remove the alias property so the whole key store is used
Regenerate or fix the key store so it contains a certificate under the configured alias
Check you are pointing at the intended key store file (path property) — the alias may exist in a different file

Example fix

// before
quarkus.tls.my-tls.key-store.p12.path=certs/server.p12
quarkus.tls.my-tls.key-store.alias=server-key
// after (alias verified via: keytool -list -keystore certs/server.p12)
quarkus.tls.my-tls.key-store.p12.path=certs/server.p12
quarkus.tls.my-tls.key-store.alias=server

Defensive patterns

Strategy: validation

Validate before calling

KeyStore ks = KeyStore.getInstance("PKCS12");
try (InputStream in = new FileInputStream(path)) { ks.load(in, storePassword); }
String alias = configAlias; // value you put in quarkus.tls...alias
if (alias != null && ks.getCertificate(alias) == null) {
    throw new IllegalArgumentException("Alias '" + alias + "' missing in " + path);
}

Try / catch

try {
    // start application / build TLS config
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("not found in key store (certificate not found)")) {
        log.errorf("Fix quarkus.tls.*.key-store.alias; available aliases: %s", Collections.list(ks.aliases()));
    }
    throw e;
}

Prevention

Run keytool -list -keystore <file> and paste exact alias names into config
Keep one canonical script that generates keystores so aliases stay stable across environments
Add a startup smoke test that loads the keystore and asserts the alias exists
Avoid hand-editing alias names in config; generate config from a template checked into CI

When it happens

Trigger: Configuring quarkus.tls.<name>.key-store.alias (or certificate key-store alias) with a name that does not exist in the P12/JKS/PEM key store file; verifyKeyStoreAlias calls KeyStore.getCertificate(alias) which returns null.

Common situations: Typo in alias name; renaming an alias when regenerating the keystore with keytool; copying config between environments whose keystores differ; case-sensitivity mistakes (aliases are case-insensitive in JKS but the configured value must still match what the store contains).

Understand the failure class

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/6168b4f91bcbf965. Report an issue: GitHub.