apache/hadoop · error · IOException

"Could not parse encryption zone for inode " + iip.getPath()

Error message

"Could not parse encryption zone for inode " + iip.getPath()

What it means

IOException('Could not parse encryption zone for inode <path>') from EncryptionZoneManager: while resolving an inode's encryption zone (cold path, when the zone is not already in the manager's cache), the raw.hdfs.crypto.encryption.zone xattr was found on the directory but ZoneEncryptionInfoProto.parseFrom() threw InvalidProtocolBufferException. The stored xattr payload is corrupt or was written in a format this NameNode version does not understand.

Source

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

      }
      if (snapshotID == Snapshot.CURRENT_STATE_ID) {
        final EncryptionZoneInt ezi = encryptionZones.get(inode.getId());
        if (ezi != null) {
          return ezi;
        }
      } else {
        XAttr xAttr = FSDirXAttrOp.unprotectedGetXAttrByPrefixedName(
            inode, snapshotID, CRYPTO_XATTR_ENCRYPTION_ZONE);
        if (xAttr != null) {
          try {
            final HdfsProtos.ZoneEncryptionInfoProto ezProto =
                HdfsProtos.ZoneEncryptionInfoProto.parseFrom(xAttr.getValue());
            return new EncryptionZoneInt(
                inode.getId(), PBHelperClient.convert(ezProto.getSuite()),
                PBHelperClient.convert(ezProto.getCryptoProtocolVersion()),
                ezProto.getKeyName());
          } catch (InvalidProtocolBufferException e) {
            throw new IOException("Could not parse encryption zone for inode "
                + iip.getPath(), e);
          }
        }
      }
    }
    return null;
  }

  /**
   * Looks up the nearest ancestor EncryptionZoneInt that contains the given
   * path (excluding itself).
   * Returns null if path is not within an EZ, or the path is the root dir '/'
   * <p>
   * Called while holding the FSDirectory lock.
   */
  private EncryptionZoneInt getParentEncryptionZoneForPath(INodesInPath iip)
      throws  IOException {
    assert dir.hasReadLock();

View on GitHub (pinned to 2add963021)

Solutions

As the HDFS superuser, dump the xattr to confirm corruption: hdfs dfs -getfattr -e hex -n raw.hdfs.crypto.encryption.zone <path> (garbage or empty hex confirms it).
Remove the corrupt xattr and recreate the zone with the same key: hdfs dfs -setfattr -x raw.hdfs.crypto.encryption.zone <path>, then hdfs crypto -createZone -keyName <sameKey> <path>.
If caused by version skew, temporarily run the Hadoop release that wrote the xattr, verify the zone, then complete a supported upgrade path.
Data safety: after recreating the zone, re-encrypt existing files via re-encryption (hdfs crypto -reencryptZone -start -path <zone>) or copy-out/copy-in.

Example fix

# before: every op under /secure fails: Could not parse encryption zone for inode /secure
hdfs dfs -getfattr -e hex -n raw.hdfs.crypto.encryption.zone /secure   # unreadable hex
# after: drop the corrupt marker, recreate the zone with the same key
hdfs dfs -setfattr -x raw.hdfs.crypto.encryption.zone /secure
hdfs crypto -createZone -keyName mykey /secure

Defensive patterns

Strategy: try-catch

Validate before calling

# as HDFS superuser: dump the zone xattr and check it is sane hex
hdfs dfs -getfattr -e hex -n raw.hdfs.crypto.encryption.zone /path
# empty / non-hex / truncated output predicts the parse failure

Try / catch

try {
  fs.create(new Path("/secure/f"));
} catch (RemoteException re) {
  IOException e = re.unwrapRemoteException(IOException.class);
  if (e.getMessage().contains("Could not parse encryption zone")) {
    // quarantine the subtree: drop raw.hdfs.crypto.encryption.zone on that dir, recreate the zone, re-encrypt
  } else { throw e; }
}

Prevention

Never set raw.* xattrs by hand; only hdfs crypto tooling owns them.
Upgrade/downgrade through supported release paths; avoid skipping versions on clusters with encryption zones.
Back up the name dir (or run HA) so xattr corruption is restorable.
After any restore, run hdfs crypto -listZones across the tree to catch unparseable zones early.

When it happens

Trigger: Any operation under the affected directory that triggers getEncryptionZoneForPath/getPathEncryptionZone (create, rename, listZones rebuild): the xattr bytes are not a valid ZoneEncryptionInfoProto -- e.g., hand-written or legacy-format raw xattr, bit rot, or metadata restored from a mismatched-version backup.

Common situations: Upgrade/downgrade across Hadoop versions with encryption zones; someone set raw.* xattrs manually with setfattr; name-dir restored from an inconsistent snapshot; partially written xattr after an old crash.

Related errors

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