apache/hadoop · error · IOException

Attempt to create an encryption zone for a file.

Error message

Attempt to create an encryption zone for a file.

What it means

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.

Source

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

  /**
   * Create a new encryption zone.
   * <p>
   * Called while holding the FSDirectory lock.
   */
  XAttr createEncryptionZone(INodesInPath srcIIP, CipherSuite suite,
      CryptoProtocolVersion version, String keyName)
      throws IOException {
    assert dir.hasWriteLock();

    // Check if src is a valid path for new EZ creation
    if (srcIIP.getLastINode() == null) {
      throw new FileNotFoundException("cannot find " + srcIIP.getPath());
    }

    INode srcINode = srcIIP.getLastINode();
    if (!srcINode.isDirectory()) {
      throw new IOException("Attempt to create an encryption zone for a file.");
    }

    if (hasCreatedEncryptionZone() && encryptionZones.
        get(srcINode.getId()) != null) {
      throw new IOException(
          "Directory " + srcIIP.getPath() + " is already an encryption zone.");
    }

    if (dir.isNonEmptyDirectory(srcIIP)) {
      throw new IOException(
          "Attempt to create an encryption zone for a non-empty directory.");
    }
    final HdfsProtos.ZoneEncryptionInfoProto proto =
        PBHelperClient.convert(suite, version, keyName);
    final XAttr ezXAttr = XAttrHelper
        .buildXAttr(CRYPTO_XATTR_ENCRYPTION_ZONE, proto.toByteArray());

    final List<XAttr> xattrs = Lists.newArrayListWithCapacity(1);

View on GitHub (pinned to 2add963021)

Solutions

  1. Choose (or create) a directory: hdfs dfs -mkdir -p <dir> and run createZone against it.
  2. If a stray file occupies the name, move/remove it: hdfs dfs -rm <file>, then mkdir + createZone.
  3. Remember the whole lifecycle: zone must be an EMPTY directory (next check rejects non-empty), so create zones before writing data.

Example fix

# before
hdfs dfs -touchz /secure          # file, not dir
hdfs crypto -createZone -keyName mykey /secure   # -> Attempt to create an encryption zone for a file.
# after
hdfs dfs -rm /secure
hdfs dfs -mkdir /secure
hdfs crypto -createZone -keyName mykey /secure
Defensive patterns

Strategy: validation

Validate before calling

if (fs.exists(zonePath) && !fs.getFileStatus(zonePath).isDirectory()) {
  // a file occupies the name: zones can only be created on directories
  throw new IllegalStateException(zonePath + " is a file");
}

Type guard

static boolean isExistingDirectory(FileSystem fs, Path p) throws IOException {
  return fs.exists(p) && fs.getFileStatus(p).isDirectory();
}

Try / catch

try {
  dfs.createEncryptionZone(dir, key);
} catch (RemoteException re) {
  IOException e = re.unwrapRemoteException(IOException.class);
  if (e.getMessage().contains("for a file")) { /* pick/mkdir a directory and retry */ }
  else { throw e; }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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