What causes "Key ${name} not found" in apache/hadoop?

Create the key first with createKey (or `hadoop key create`)

apache/hadoop · error · IOException

Key ${name} not found

Error message

Key ${name} not found

What it means

JavaKeyStoreProvider.rollNewVersion(name, material) requires an existing key: getMetadata(name) returned null, so there is no Metadata (cipher, bit length, version counter) to attach a new version to, and the call aborts with 'Key <name> not found' before any length check or version increment.

Source

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

    try {
      keyStore.setKeyEntry(versionName, new SecretKeySpec(material, cipher),
          password, null);
    } catch (KeyStoreException e) {
      throw new IOException("Can't store key " + versionName + " in " + this,
          e);
    }
    changed = true;
    return new KeyVersion(name, versionName, material);
  }

  @Override
  public KeyVersion rollNewVersion(String name,
                                    byte[] material) throws IOException {
    writeLock.lock();
    try {
      Metadata meta = getMetadata(name);
      if (meta == null) {
        throw new IOException("Key " + name + " not found");
      }
      if (meta.getBitLength() != 8 * material.length) {
        throw new IOException("Wrong key length. Required " +
            meta.getBitLength() + ", but got " + (8 * material.length));
      }
      int nextVersion = meta.addVersion();
      String versionName = buildVersionName(name, nextVersion);
      return innerSetKeyVersion(name, versionName, material, meta.getCipher());
    } finally {
      writeLock.unlock();
    }
  }

  @Override
  public void flush() throws IOException {
    Path newPath = constructNewPath(path);
    Path oldPath = constructOldPath(path);
    Path resetPath = path;

View on GitHub (pinned to 2add963021)

Solutions

Create the key first with createKey (or `hadoop key create`)
Guard with getMetadata(name) != null before rolling
Use the provider instance bound to the keystore that actually stores the key

Example fix

// before
provider.rollNewVersion(name, material);

// after
if (provider.getMetadata(name) == null) {
  provider.createKey(name, material, options);
} else {
  provider.rollNewVersion(name, material);
}

Defensive patterns

Strategy: validation

Validate before calling

if (provider.getMetadata(name) == null) {
  provider.createKey(name, material, options);
} else {
  provider.rollNewVersion(name, material);
}

Try / catch

try { provider.rollNewVersion(name, material); } catch (IOException e) { if (String.valueOf(e.getMessage()).endsWith("not found")) { provider.createKey(name, material, options); } else { throw e; } }

Prevention

Check getMetadata before rollNewVersion
Create keys as part of environment provisioning
Log the provider URI alongside key operations

When it happens

Trigger: Rolling a version before the key was created; a typo in the key name; the key was deleted by another process; the provider URI points at a different keystore than the one holding the key.

Common situations: Automation assuming a key exists on a fresh cluster; key name case mismatch; per-tenant keystores where the wrong tenant store is addressed.

Related errors

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