eclipse-vertx/vert.x · error · IllegalArgumentException

alias does not exist in the keystore:

Error message

alias does not exist in the keystore: 

What it means

Keystore validation in KeyStoreHelper.loadKeyStore: an alias filter was requested, but the keystore does not contain an entry with that alias name. The alias is appended to the message; the input at fault is the alias option configured on the KeyStoreOptions.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/KeyStoreHelper.java:255

    }

    return names;
  }

  public static KeyStore loadKeyStore(String type, String provider, String password, Supplier<Buffer> value, String alias) throws Exception {
    Objects.requireNonNull(type);
    KeyStore ks = provider == null ? KeyStore.getInstance(type) : KeyStore.getInstance(type, provider);
    Buffer keystoreBuffer = value.get();
    if (keystoreBuffer == null) {
      ks.load(null, password != null ? password.toCharArray() : null);
    } else {
      try (InputStream in = new ByteArrayInputStream(value.get().getBytes())) {
        ks.load(in, password != null ? password.toCharArray() : null);
      }
    }
    if (alias != null) {
      if (!ks.containsAlias(alias)) {
        throw new IllegalArgumentException("alias does not exist in the keystore: " + alias);
      }
      List<String> ksAliases = Collections.list(ks.aliases());
      for (String ksAlias : ksAliases) {
        if (!alias.equals(ksAlias)) {
          ks.deleteEntry(ksAlias);
        }
      }
    }
    return ks;
  }

  public static KeyStore loadKeyCert(List<Buffer> keyValue, List<Buffer> certValue) throws Exception {
    if (keyValue.size() < certValue.size()) {
      throw new VertxException("Missing private key");
    } else if (keyValue.size() > certValue.size()) {
      throw new VertxException("Missing X.509 certificate");
    }
    final KeyStore keyStore = createEmptyKeyStore();

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use an alias that exists in the keystore (list entries with keytool -list)
2. Remove the alias filter if the whole keystore should be used
3. Check for case-sensitive alias mismatches

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/KeyStoreHelper.java:255 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/a925eb8d8bc34924. Report an issue: GitHub.