{"record":{"id":"8f2fe56518b051b6","repo":"apache/hadoop","slug":"rename-destination-cannot-be-the-root","errorCode":null,"errorMessage":"rename destination cannot be the root","messagePattern":"rename destination cannot be the root","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirRenameOp.java","lineNumber":407,"sourceCode":"    final String src = srcIIP.getPath();\n    final String dst = dstIIP.getPath();\n    final String error;\n    final INode srcInode = srcIIP.getLastINode();\n    List<INodeDirectory> srcSnapshottableDirs = new ArrayList<>();\n    validateRenameSource(fsd, srcIIP, srcSnapshottableDirs);\n\n    // validate the destination\n    if (dst.equals(src)) {\n      throw new FileAlreadyExistsException(\"The source \" + src +\n          \" and destination \" + dst + \" are the same\");\n    }\n    validateDestination(src, dst, srcInode);\n\n    if (dstIIP.length() == 1) {\n      error = \"rename destination cannot be the root\";\n      NameNode.stateChangeLog.warn(\"DIR* FSDirectory.unprotectedRenameTo: \" +\n          error);\n      throw new IOException(error);\n    }\n\n    BlockStoragePolicySuite bsps = fsd.getBlockStoragePolicySuite();\n    fsd.ezManager.checkMoveValidity(srcIIP, dstIIP);\n    final INode dstInode = dstIIP.getLastINode();\n    List<INodeDirectory> dstSnapshottableDirs = new ArrayList<>();\n    if (dstInode != null) { // Destination exists\n      validateOverwrite(src, dst, overwrite, srcInode, dstInode);\n      FSDirSnapshotOp.checkSnapshot(fsd, dstIIP, dstSnapshottableDirs);\n    }\n\n    INode dstParent = dstIIP.getINode(-2);\n    if (dstParent == null) {\n      error = \"rename destination parent \" + dst + \" not found.\";\n      NameNode.stateChangeLog.warn(\"DIR* FSDirectory.unprotectedRenameTo: \" +\n          error);\n      throw new FileNotFoundException(error);\n    }","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirRenameOp.java#L389-L425","documentation":"IOException thrown when the rename destination resolves to the filesystem root (dstIIP.length() == 1). The root always exists and is immutable as a rename target, so 'rename to /' is rejected during destination validation before quota or overwrite checks.","triggerScenarios":"`hdfs dfs -mv /data /` where the destination normalizes to the root; programmatic fs.rename(src, new Path(\"/\")); destination strings built by concatenation that end up empty and default to '/'.","commonSituations":"Scripts intending 'move up one level' - in HDFS the destination must be the full new path (/data2), not /; template bugs stripping the file name and leaving the root; copying commands between posix mv semantics and HDFS semantics.","solutions":["Give the destination a real name: `hdfs dfs -mv /data /data2` (HDFS rename has no 'move into directory' form - dst is the final path).","Validate in code that dst is not root (dst.isRoot()) before calling rename."],"exampleFix":"# before\nhdfs dfs -mv /data /      # IOException: rename destination cannot be the root\n\n# after\nhdfs dfs -mv /data /data2","handlingStrategy":"validation","validationCode":"if (dst.isRoot()) {\n  throw new IllegalArgumentException(\"Rename destination cannot be the root; give the destination a name\");\n}\nfs.rename(src, dst);","typeGuard":null,"tryCatchPattern":"try {\n  fs.rename(src, dst);\n} catch (IOException e) {\n  if (dst.isRoot() && e.getMessage().contains(\"cannot be the root\")) {\n    // rebuild dst as parent-of-src + new name\n    dst = new Path(src.getParent(), newDstName);\n    fs.rename(src, dst);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Remember HDFS rename has no 'move into directory' form; the destination is the full final path.","Reject empty/normalized-to-root destinations in path-building helpers."],"tags":["hdfs","rename","root-path","path-validation"],"backgroundTag":"rename-to-root","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}