{"record":{"id":"72caadb4e47e4dab","repo":"apache/hadoop","slug":"key-keyname-doesn-t-exist","errorCode":null,"errorMessage":"\"Key \" + keyName + \" doesn't exist.\"","messagePattern":"\"Key \" \\+ keyName \\+ \" doesn't exist\\.\"","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirEncryptionZoneOp.java","lineNumber":136,"sourceCode":"      throw new IOException(\"Can't create an encryption zone for \" + src\n          + \" since no key provider is available.\");\n    }\n    if (keyName == null || keyName.isEmpty()) {\n      throw new IOException(\"Must specify a key name when creating an \"\n          + \"encryption zone\");\n    }\n    EncryptionFaultInjector.getInstance().ensureKeyIsInitialized();\n    KeyProvider.Metadata metadata = provider.getMetadata(keyName);\n    if (metadata == null) {\n      /*\n       * It would be nice if we threw something more specific than\n       * IOException when the key is not found, but the KeyProvider API\n       * doesn't provide for that. If that API is ever changed to throw\n       * something more specific (e.g. UnknownKeyException) then we can\n       * update this to match it, or better yet, just rethrow the\n       * KeyProvider's exception.\n       */\n      throw new IOException(\"Key \" + keyName + \" doesn't exist.\");\n    }\n    // If the provider supports pool for EDEKs, this will fill in the pool\n    provider.warmUpEncryptedKeys(keyName);\n    return metadata;\n  }\n\n  /**\n   * Create an encryption zone on directory path using the specified key.\n   *\n   * @param fsd the namespace tree.\n   * @param srcArg the path of a directory which will be the root of the\n   *               encryption zone. The directory must be empty\n   * @param pc permission checker to check fs permission\n   * @param cipher the name of the cipher suite, which will be used\n   *               when it is generated.\n   * @param keyName name of a key which must be present in the configured\n   *                KeyProvider\n   * @param logRetryCache whether to record RPC ids in editlog for retry cache","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirEncryptionZoneOp.java#L118-L154","documentation":"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.","triggerScenarios":"'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.","commonSituations":"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.","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."],"exampleFix":"# before\nhdfs crypto -createZone -key mykey -path /secure  # mykey never created\n\n# after\nhadoop key create mykey -size 128\nhdfs crypto -createZone -key mykey -path /secure","handlingStrategy":"validation","validationCode":"KeyProvider kp = KeyProviderFactory.get(conf); // resolves the same provider chain\nif (kp.getMetadata(keyName) == null) {\n  throw new IllegalArgumentException(\n      \"Key '\" + keyName + \"' not found; create it first: hadoop key create \" + keyName);\n}","typeGuard":null,"tryCatchPattern":"catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"doesn't exist\")) {\n    // create the key (idempotent check first), then retry zone creation once\n    ensureKeyExists(conf, keyName);\n    admin.createEncryptionZone(path, keyName);\n  } else { throw e; }\n}","preventionTips":["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."],"tags":["hdfs","encryption-zone","kms","key-not-found","tde"],"backgroundTag":"encryption-key-not-found","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}