apache/iceberg · error · ValidationException

Unknown key element %s

Error message

Unknown key element %s

What it means

CachedClientPool.extractKey() throws ValidationException when an entry in the configured client-pool key (e.g. HiveConf client pool key elements) is not one of the recognized KeyElementType values (UGI, USER_NAME, etc.). It means an unknown element was supplied in the comma-separated key-element configuration.

Source

Thrown at hive-metastore/src/main/java/org/apache/iceberg/hive/CachedClientPool.java:160

    Map<String, String> confElements = Maps.newTreeMap();
    for (String element : cacheKeys.split(",", -1)) {
      String trimmed = element.trim();
      if (trimmed.toLowerCase(Locale.ROOT).startsWith(CONF_ELEMENT_PREFIX)) {
        String key = trimmed.substring(CONF_ELEMENT_PREFIX.length());
        ValidationException.check(
            !confElements.containsKey(key), "Conf key element %s already specified", key);
        confElements.put(key, conf.get(key));
      } else {
        KeyElementType type = KeyElementType.valueOf(trimmed.toUpperCase(Locale.ROOT));
        switch (type) {
          case UGI:
          case USER_NAME:
            ValidationException.check(
                !types.contains(type), "%s key element already specified", type.name());
            types.add(type);
            break;
          default:
            throw new ValidationException("Unknown key element %s", trimmed);
        }
      }
    }
    for (KeyElementType type : types) {
      switch (type) {
        case UGI:
          try {
            elements.add(UserGroupInformation.getCurrentUser());
          } catch (IOException e) {
            throw new UncheckedIOException(e);
          }
          break;
        case USER_NAME:
          try {
            elements.add(UserGroupInformation.getCurrentUser().getUserName());
          } catch (IOException e) {
            throw new UncheckedIOException(e);
          }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Fix the key-element configuration to use only supported values (ugi, user_name)
2. Check the KeyElementType enum in the Iceberg version you use for exact names
3. Remove unknown elements from the client-pool key configuration

Example fix

// before
client.pool.key-elements = user,ugi
// after
client.pool.key-elements = user_name,ugi

Set<String> valid = Set.of("ugi","user_name"); // check every configured element against KeyElementType names before building the pool

try { new CachedClientPool(dbName, conf, keyElements, ...); } catch (ValidationException e) { /* log bad element name, fall back to defaults */ }

When it happens

Trigger: Setting the client-pool key-element property to a token that does not match any KeyElementType enum, e.g. a typo or unsupported element name; extractKey() parses the trimmed tokens in a switch and hits default.

Common situations: Typo in configuration (e.g. 'ugi ' vs 'UGI' handled, but 'user' vs 'username' not); upgrading Iceberg where an element name changed; copying config from another connector with different element names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid distribution mode: %s
• Failed to acquire locks from metastore because the underlyin
• Cannot initialize AliyunClientFactory, missing no-arg constr
• Invalid file format: %s
• Unsorted order ID must be 0

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/44be4777d8ea0678. Report an issue: GitHub.