{"record":{"id":"598039836674eee4","repo":"apache/hadoop","slug":"must-specify-a-key-name-when-creating-an-encryptio","errorCode":null,"errorMessage":"Must specify a key name when creating an encryption zone","messagePattern":"Must specify a key name when creating an encryption zone","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":122,"sourceCode":"              throw new IOException(e);\n            }\n          }\n        });\n    long generateEDEKTime = monotonicNow() - generateEDEKStartTime;\n    NameNode.getNameNodeMetrics().addGenerateEDEKTime(generateEDEKTime);\n    Preconditions.checkNotNull(edek);\n    return edek;\n  }\n\n  static KeyProvider.Metadata ensureKeyIsInitialized(final FSDirectory fsd,\n      final String keyName, final String src) throws IOException {\n    KeyProviderCryptoExtension provider = fsd.getProvider();\n    if (provider == null) {\n      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;","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirEncryptionZoneOp.java#L104-L140","documentation":"ensureKeyIsInitialized rejects a null or empty keyName with IOException before it ever contacts the key provider: an encryption zone must be bound to a named key so the NameNode can later generate EDEKs for files in the zone. This is purely argument validation after the provider check — the key itself need not exist yet at this line (a missing key fails later with 'Key ... doesn't exist').","triggerScenarios":"HdfsAdmin.createEncryptionZone(path, null) or with an empty string; shell wrapper scripts calling 'hdfs crypto -createZone -path <p>' without -key; code that reads the key name from config/environment and passes it through unvalidated.","commonSituations":"Automation templates with an unset ${KEY_NAME} variable that expands to empty; config-driven provisioning where the key property was renamed but the code still reads the old name; interactive scripts where the -key flag is optional but zone creation is not.","solutions":["Supply a non-empty key name: 'hdfs crypto -createZone -key mykey -path /secure'.","Validate the keyName argument in your provisioning code (Preconditions.checkNotNull + isNotEmpty) before calling HdfsAdmin.","Fail fast in deploy scripts when the key-name variable is unset instead of passing it through."],"exampleFix":"# before\nhdfs crypto -createZone -path /secure  # no -key\n\n# after\nhdfs crypto -createZone -key mykey -path /secure","handlingStrategy":"validation","validationCode":"if (keyName == null || keyName.trim().isEmpty()) {\n  throw new IllegalArgumentException(\"Encryption zone requires a non-empty key name\");\n}\nadmin.createEncryptionZone(path, keyName);","typeGuard":null,"tryCatchPattern":"catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"Must specify a key name\")) {\n    throw new IllegalArgumentException(\"Fix provisioning config: key name was empty\", e);\n  }\n  throw e;\n}","preventionTips":["Validate the key-name variable early in provisioning scripts; fail before touching the cluster.","Make -key mandatory in wrapper scripts around 'hdfs crypto -createZone'.","Watch for config-template placeholders (e.g. empty ${KEY_NAME}) expanding to blank strings."],"tags":["hdfs","encryption-zone","invalid-argument","key-name"],"backgroundTag":"encryption-zone-missing-key-name","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}