quarkusio/quarkus · error · java.lang.IllegalStateException

Alias '${alias}' not found in trust store (certificate not f

Error message

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

What it means

The TLS registry verifies that the alias configured for a trust store exists and contains a certificate. This error means the trust store loaded, but KeyStore.getCertificate(alias) returned null — no certificate under that alias. Fails fast at startup instead of failing during TLS trust evaluation.

Source

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

                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);
            }
        }
    }

    private static void verifyTrustStoreAlias(Optional<String> maybeAlias, String name, KeyStore ks) {
        if (maybeAlias.isPresent()) {
            String alias = maybeAlias.get();
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in trust store (certificate not found) '" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException(
                        "Unable to verify alias '" + alias + "' in trust store '" + name + "'", e);
            }
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

List aliases with keytool -list -keystore <truststore> and use an existing alias
Remove the alias property to trust all certificates in the trust store
Re-import the CA certificate under the expected alias: keytool -importcert -alias <alias>
Confirm the trust-store path points at the intended file

Example fix

// before
quarkus.tls.my-tls.trust-store.p12.alias=my-ca
// after (alias from keytool -list)
quarkus.tls.my-tls.trust-store.p12.alias=internal-root-ca

Defensive patterns

Strategy: validation

Validate before calling

KeyStore ts = /* load trust store */;
String alias = configAlias;
if (alias != null && ts.getCertificate(alias) == null) {
    throw new IllegalArgumentException("Trust store missing cert alias '" + alias + "'");
}

Prevention

List trust store aliases with keytool -list before configuring alias
Prefer omitting the alias to trust the entire store unless you need restriction
Keep CA import scripts declarative so aliases are reproducible
Validate trust store config in integration tests

When it happens

Trigger: Setting quarkus.tls.<name>.trust-store.alias (or per-trust-store alias) to a name not present in the trust store file; verifyTrustStoreAlias finds no certificate for it.

Common situations: Typo in alias; trust store regenerated with different alias names; copying trust-store config from a project using a different CA bundle; case or whitespace differences in the alias string.

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