quarkusio/quarkus · error · java.lang.IllegalStateException

Unable to verify alias

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.

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.

Appendix: 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)