What causes ""Key " + keyName + " doesn't exist."" in apache/hadoop?

Create the key first: hadoop key create (optionally -size 128 -algorithm AES).

apache/hadoop · error · IOException

"Key " + keyName + " doesn't exist."

Error message

"Key " + keyName + " doesn't exist."

What it means

After confirming a provider and a non-empty name, ensureKeyIsInitialized asks the KeyProvider for the key's metadata; a null result means no such key exists in the KMS and IOException 'Key <name> doesn't exist.' is thrown. The comment in the source notes the KeyProvider API has no key-not-found exception type, so it surfaces as a generic IOException. Zone creation is aborted before any XAttr is written.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirEncryptionZoneOp.java:136

      throw new IOException("Can't create an encryption zone for " + src
          + " since no key provider is available.");
    }
    if (keyName == null || keyName.isEmpty()) {
      throw new IOException("Must specify a key name when creating an "
          + "encryption zone");
    }
    EncryptionFaultInjector.getInstance().ensureKeyIsInitialized();
    KeyProvider.Metadata metadata = provider.getMetadata(keyName);
    if (metadata == null) {
      /*
       * It would be nice if we threw something more specific than
       * IOException when the key is not found, but the KeyProvider API
       * doesn't provide for that. If that API is ever changed to throw
       * something more specific (e.g. UnknownKeyException) then we can
       * update this to match it, or better yet, just rethrow the
       * KeyProvider's exception.
       */
      throw new IOException("Key " + keyName + " doesn't exist.");
    }
    // If the provider supports pool for EDEKs, this will fill in the pool
    provider.warmUpEncryptedKeys(keyName);
    return metadata;
  }

  /**
   * Create an encryption zone on directory path using the specified key.
   *
   * @param fsd the namespace tree.
   * @param srcArg the path of a directory which will be the root of the
   *               encryption zone. The directory must be empty
   * @param pc permission checker to check fs permission
   * @param cipher the name of the cipher suite, which will be used
   *               when it is generated.
   * @param keyName name of a key which must be present in the configured
   *                KeyProvider
   * @param logRetryCache whether to record RPC ids in editlog for retry cache

View on GitHub (pinned to 2add963021)

Solutions

Create the key first: hadoop key create <keyName> (optionally -size 128 -algorithm AES).
Verify the key is visible through the same provider the NameNode uses: hadoop key list -metadata.
Check for typos and case differences between the -key argument and the actual key name.
If the key exists elsewhere, point hadoop.security.key.provider.path at the right KMS or re-create the key in this KMS.

Example fix

# before
hdfs crypto -createZone -key mykey -path /secure  # mykey never created

# after
hadoop key create mykey -size 128
hdfs crypto -createZone -key mykey -path /secure

Defensive patterns

Strategy: validation

Validate before calling

KeyProvider kp = KeyProviderFactory.get(conf); // resolves the same provider chain
if (kp.getMetadata(keyName) == null) {
  throw new IllegalArgumentException(
      "Key '" + keyName + "' not found; create it first: hadoop key create " + keyName);
}

Try / catch

catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("doesn't exist")) {
    // create the key (idempotent check first), then retry zone creation once
    ensureKeyExists(conf, keyName);
    admin.createEncryptionZone(path, keyName);
  } else { throw e; }
}

Prevention

Run 'hadoop key list' (or getMetadata via KeyProvider) before zone creation and create missing keys up front.
Pin exact key names in config with a checksum/format lint to catch typos.
In multi-cluster setups, confirm the NameNode's provider URI points at the KMS that actually holds the key.

When it happens

Trigger: 'hdfs crypto -createZone -key <name> -path <p>' where <name> was never created in the KMS; key created in a different KMS than the one the NameNode points at (per-cluster KMS with mismatched provider URI); key deleted after a prior run; simple typo in the key name.

Common situations: Fresh TDE setup where the admin forgot 'hadoop key create'; multi-cluster environments sharing config but not KMS contents; key lifecycle rotation where an old key was deleted while provisioning scripts still reference it; lowercase/uppercase drift in key names.

Related errors

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