apache/hadoop · error · InvalidPathException

Cannot rename to or from /.reserved

Error message

Cannot rename to or from /.reserved

What it means

InvalidPathException when either endpoint of the rename is exactly '/.reserved' (FSDirectory.isExactReservedName). /.reserved is a virtual namespace exposing internal state (e.g., /.reserved/raw for raw encrypted bytes) and cannot be created, deleted, or renamed as a whole; its children like /.reserved/raw/<path> are addressed individually.

Source

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

    if (srcInode.isSymlink() &&
        dst.equals(srcInode.asSymlink().getSymlinkString())) {
      throw new FileAlreadyExistsException("Cannot rename symlink " + src
          + " to its target " + dst);
    }
    // dst cannot be a directory or a file under src
    if (dst.startsWith(src)
        && dst.charAt(src.length()) == Path.SEPARATOR_CHAR) {
      error = "Rename destination " + dst
          + " is a directory or file under source " + src;
      NameNode.stateChangeLog.warn("DIR* FSDirectory.unprotectedRenameTo: "
          + error);
      throw new IOException(error);
    }

    if (FSDirectory.isExactReservedName(src)
        || FSDirectory.isExactReservedName(dst)) {
      error = "Cannot rename to or from /.reserved";
      throw new InvalidPathException(error);
    }
  }

  private static void validateOverwrite(
      String src, String dst, boolean overwrite, INode srcInode, INode dstInode)
      throws IOException {
    String error;// It's OK to rename a file to a symlink and vice versa
    if (dstInode.isDirectory() != srcInode.isDirectory()) {
      error = "Source " + src + " and destination " + dst
          + " must both be directories";
      NameNode.stateChangeLog.warn("DIR* FSDirectory.unprotectedRenameTo: "
          + error);
      throw new IOException(error);
    }
    if (!overwrite) { // If destination exists, overwrite flag must be true
      error = "rename destination " + dst + " already exists";
      NameNode.stateChangeLog.warn("DIR* FSDirectory.unprotectedRenameTo: "
          + error);

View on GitHub (pinned to 2add963021)

Solutions

1. Exclude /.reserved from any move/rename logic (skip reserved names).
2. To operate on raw zone contents, address /.reserved/raw/<real-path> explicitly instead of renaming the reserved root.
3. Whitelist known-good top-level directories rather than blacklisting.

Example fix

# before
hdfs dfs -mv /.reserved /backup/.reserved   # InvalidPathException

# after
# /.reserved is virtual: skip it entirely in move scripts
hdfs dfs -mv /data /backup/data

static boolean isReservedRoot(Path p) {
  return "/.reserved".equals(p.toUri().getPath());
}
if (isReservedRoot(src) || isReservedRoot(dst)) {
  throw new org.apache.hadoop.fs.InvalidPathException("Cannot rename to or from /.reserved");
}
fs.rename(src, dst);

try {
  fs.rename(src, dst);
} catch (InvalidPathException e) {
  // /.reserved is a virtual namespace; skip it in move/backup logic
  throw e;
}

When it happens

Trigger: `hdfs dfs -mv /.reserved /backup`; programmatic rename with either Path equal to /.reserved; backup/migration tools that iterate top-level entries of / and attempt to move the reserved node.

Common situations: Backup or tree-copy scripts walking '/' naively; experiments embedding /.reserved into path templates; security audits that try to relocate the raw view.

Related errors

• {} doesn't support renameSnapshot
• Could not rename {oldDir} to {newDir}
• Cannot delete/rename non-empty protected directory {}
• Cannot delete/rename non-empty protected subdirectory {}
• Cannot delete/rename subdirectory under protected subdirecto

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