apache/hadoop · error · IOException

Can't cast key for ${name} in keystore ${path} to a KeyMetad

Error message

Can't cast key for ${name} in keystore ${path} to a KeyMetadata. Key may have been added using  keytool or some other non-Hadoop method.

What it means

JavaKeyStoreProvider stores key metadata as a special key entry whose class is KeyProvider.KeyMetadata. getMetadata() casts the keystore entry to KeyMetadata; a ClassCastException means an alias with that name exists but holds a different entry type — i.e. it was created outside Hadoop (keytool, third-party tool) rather than by a Hadoop KeyProvider.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/key/JavaKeyStoreProvider.java:415

    }
  }

  @Override
  public Metadata getMetadata(String name) throws IOException {
    readLock.lock();
    try {
      if (cache.containsKey(name)) {
        return cache.get(name);
      }
      try {
        if (!keyStore.containsAlias(name)) {
          return null;
        }
        Metadata meta = ((KeyMetadata) keyStore.getKey(name, password)).metadata;
        cache.put(name, meta);
        return meta;
      } catch (ClassCastException e) {
        throw new IOException("Can't cast key for " + name + " in keystore " +
            path + " to a KeyMetadata. Key may have been added using " +
            " keytool or some other non-Hadoop method.", e);
      } catch (KeyStoreException e) {
        throw new IOException("Can't get metadata for " + name +
            " from keystore " + path, e);
      } catch (NoSuchAlgorithmException e) {
        throw new IOException("Can't get algorithm for " + name +
            " from keystore " + path, e);
      } catch (UnrecoverableKeyException e) {
        throw new IOException("Can't recover key for " + name +
            " from keystore " + path, e);
      }
    } finally {
      readLock.unlock();
    }
  }

  @Override

View on GitHub (pinned to 2add963021)

Solutions

1. Inspect the alias: keytool -list -keystore <path> -storetype jceks and compare entry types
2. Remove or rename the non-Hadoop alias: keytool -delete -alias <name> (or -changealias), after exporting any needed secret elsewhere
3. Re-create the key through KMS/Hadoop APIs (hadoop key create) so it carries proper KeyMetadata
4. Keep keytool-managed credentials in a separate keystore file from the Hadoop KMS keystore

Example fix

# before: alias 'mykey' was added via keytool -> getMetadata throws
keytool -list -keystore ks.jks -storetype jceks   # shows non-Hadoop entry

# after: move the foreign secret out, then recreate via Hadoop
keytool -importkeystore ... # export the secret elsewhere if needed
keytool -delete -alias mykey -keystore ks.jks -storetype jceks
hadoop key create mykey -size 128 -provider jceks://file/etc/security/ks.jks

// Detect foreign entries before they break key operations
KeyStore ks = KeyStore.getInstance("jceks");
ks.load(in, pwd);
if (ks.containsAlias(name) && !ks.isKeyEntry(name)) {
  throw new IllegalStateException("Alias " + name + " is not a Hadoop key entry; managed with keytool?");
}

// Heuristic guard: Hadoop-managed keystores contain a '_metadata' companion alias
public boolean looksLikeHadoopManaged(KeyStore ks, String name) throws KeyStoreException {
  return ks.containsAlias(name + "_metadata");
}

try {
  Metadata m = provider.getMetadata(name);
} catch (IOException e) {
  if (e.getCause() instanceof ClassCastException) {
    // alias exists but was created by keytool: delete/rename it, then create via Hadoop API
  }
}

When it happens

Trigger: KeyProvider.getMetadata(name) or any key operation (createKey/rollover/delete triggers metadata lookup) where an admin previously ran keytool -genseckey / -importpassword with an alias identical to the Hadoop key name in the same JCEKS file.

Common situations: Admins mixing keytool-managed secrets and Hadoop KMS keys in one keystore file; migrating credentials manually with keytool into the KMS keystore; tooling that writes generic JCEKS entries into the provider path

Related errors

• Can't get metadata for ${name} from keystore ${path}
• Can't recover key for ${name} from keystore ${path}
• Keystore not loaded due to some inconsistency ('%s' and '%s'
• Can't create keystore: ${e}
• Can't load keystore ${path} : ${e}

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/db26f67dbc62108d. Report an issue: GitHub.