{"record":{"id":"ee590e86d7037354","repo":"apache/hadoop","slug":"attempt-to-create-an-encryption-zone-for-a-file","errorCode":null,"errorMessage":"Attempt to create an encryption zone for a file.","messagePattern":"Attempt to create an encryption zone for a file\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/EncryptionZoneManager.java","lineNumber":547,"sourceCode":"\n  /**\n   * Create a new encryption zone.\n   * <p>\n   * Called while holding the FSDirectory lock.\n   */\n  XAttr createEncryptionZone(INodesInPath srcIIP, CipherSuite suite,\n      CryptoProtocolVersion version, String keyName)\n      throws IOException {\n    assert dir.hasWriteLock();\n\n    // Check if src is a valid path for new EZ creation\n    if (srcIIP.getLastINode() == null) {\n      throw new FileNotFoundException(\"cannot find \" + srcIIP.getPath());\n    }\n\n    INode srcINode = srcIIP.getLastINode();\n    if (!srcINode.isDirectory()) {\n      throw new IOException(\"Attempt to create an encryption zone for a file.\");\n    }\n\n    if (hasCreatedEncryptionZone() && encryptionZones.\n        get(srcINode.getId()) != null) {\n      throw new IOException(\n          \"Directory \" + srcIIP.getPath() + \" is already an encryption zone.\");\n    }\n\n    if (dir.isNonEmptyDirectory(srcIIP)) {\n      throw new IOException(\n          \"Attempt to create an encryption zone for a non-empty directory.\");\n    }\n    final HdfsProtos.ZoneEncryptionInfoProto proto =\n        PBHelperClient.convert(suite, version, keyName);\n    final XAttr ezXAttr = XAttrHelper\n        .buildXAttr(CRYPTO_XATTR_ENCRYPTION_ZONE, proto.toByteArray());\n\n    final List<XAttr> xattrs = Lists.newArrayListWithCapacity(1);","sourceCodeStart":529,"sourceCodeEnd":565,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/EncryptionZoneManager.java#L529-L565","documentation":"IOException('Attempt to create an encryption zone for a file.') from createEncryptionZone: the path resolves to an existing inode, but it is a file, not a directory. Encryption zones are directory-level markers (the raw.hdfs.crypto.encryption.zone xattr) applied to directories so all files beneath inherit encryption; a single file cannot be a zone.","triggerScenarios":"hdfs crypto -createZone -keyName <key> <path> where <path> is a regular file; commonly a path collision where the expected directory was never made because a file of the same name already exists.","commonSituations":"Provisioning scripts that create a marker file then try to zone it; path planning mistakes (pointing at /data/file.csv instead of /data); leftover files blocking the intended directory name.","solutions":["Choose (or create) a directory: hdfs dfs -mkdir -p <dir> and run createZone against it.","If a stray file occupies the name, move/remove it: hdfs dfs -rm <file>, then mkdir + createZone.","Remember the whole lifecycle: zone must be an EMPTY directory (next check rejects non-empty), so create zones before writing data."],"exampleFix":"# before\nhdfs dfs -touchz /secure          # file, not dir\nhdfs crypto -createZone -keyName mykey /secure   # -> Attempt to create an encryption zone for a file.\n# after\nhdfs dfs -rm /secure\nhdfs dfs -mkdir /secure\nhdfs crypto -createZone -keyName mykey /secure","handlingStrategy":"validation","validationCode":"if (fs.exists(zonePath) && !fs.getFileStatus(zonePath).isDirectory()) {\n  // a file occupies the name: zones can only be created on directories\n  throw new IllegalStateException(zonePath + \" is a file\");\n}","typeGuard":"static boolean isExistingDirectory(FileSystem fs, Path p) throws IOException {\n  return fs.exists(p) && fs.getFileStatus(p).isDirectory();\n}","tryCatchPattern":"try {\n  dfs.createEncryptionZone(dir, key);\n} catch (RemoteException re) {\n  IOException e = re.unwrapRemoteException(IOException.class);\n  if (e.getMessage().contains(\"for a file\")) { /* pick/mkdir a directory and retry */ }\n  else { throw e; }\n}","preventionTips":["Provision zones on freshly mkdir'd empty directories before any data is written.","Guard scripts with an isDirectory() check on the zone path.","Remember the follow-on rule: the directory must also be empty at creation time."],"tags":["hdfs","encryption-zone","path-type","provisioning"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}