{"record":{"id":"a155735086d297fc","repo":"apache/hadoop","slug":"symlinks-unsupported","errorCode":null,"errorMessage":"Symlinks unsupported","messagePattern":"Symlinks unsupported","errorType":"exception","errorClass":"PathIOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/SetReplication.java","lineNumber":84,"sourceCode":"      displayWarning(\"Illegal replication, a positive integer expected\");\n      throw nfe;\n    }\n    if (newRep < 1) {\n      throw new IllegalArgumentException(\"replication must be >= 1\");\n    }\n  }\n\n  @Override\n  protected void processArguments(LinkedList<PathData> args)\n  throws IOException {\n    super.processArguments(args);\n    if (waitOpt) waitForReplication();\n  }\n\n  @Override\n  protected void processPath(PathData item) throws IOException {\n    if (item.stat.isSymlink()) {\n      throw new PathIOException(item.toString(), \"Symlinks unsupported\");\n    }\n    \n    if (item.stat.isFile()) {\n      // Do the checking if the file is erasure coded since\n      // replication factor for an EC file is meaningless.\n      if (!item.stat.isErasureCoded()) {\n        if (!item.fs.setReplication(item.path, newRep)) {\n          throw new IOException(\"Could not set replication for: \" + item);\n        }\n        out.println(\"Replication \" + newRep + \" set: \" + item);\n        if (waitOpt) {\n          waitList.add(item);\n        }\n      } else {\n        out.println(\"Did not set replication for: \" + item\n            + \", because it's an erasure coded file.\");\n      }\n    } ","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/SetReplication.java#L66-L102","documentation":"SetReplication.processPath (SetReplication.java:84) throws PathIOException(item, 'Symlinks unsupported') when the enumerated path's FileStatus.isSymlink() is true. Because -setrep runs with setRecursive(true), every child in the tree is checked, and any symlink (file or its target chain) aborts that item. Replication is a property of the target's blocks, so setting it 'through' a link is ambiguous and refused.","triggerScenarios":"'hadoop fs -setrep 3 /dir' where /dir or any file under it is a symlink (created via FileSystem.createSymlink / -put with symlinks preserved); running setrep on an HDFS tree containing symlinked entries.","commonSituations":"Ingestion trees that materialize symlinks (e.g., manifest-style datasets, Hive-style symlink tables); migrating data with symlinked convenience names; EC/replication sweeps over user directories where users added symlinks.","solutions":["Run -setrep on the symlink target path(s) directly instead of through the link","Exclude or remove the symlinks from the tree ('hadoop fs -ls' and filter, or hdfs dfsadmin-level tooling) before the recursive setrep","In code, pre-check FileStatus.isSymlink() and resolve via getSymlinkLink()/Path(target) before calling setReplication"],"exampleFix":"# before\nhadoop fs -setrep -w 3 /data/manifest   # contains a symlink\n# setrep: Symlinks unsupported\n\n# after\nhadoop fs -ls /data/manifest            # identify the link\nhadoop fs -setrep -w 3 /data/manifest/real-file-1 /data/manifest/real-file-2","handlingStrategy":"type-guard","validationCode":"for (FileStatus st : fs.listStatus(dir)) {\n  if (st.isSymlink()) continue; // or resolve: new Path(st.getSymlink())\n  fs.setReplication(st.getPath(), rep);\n}","typeGuard":"boolean setrepSafe(FileStatus st) {\n  return !st.isSymlink() && st.isFile() && !st.isErasureCoded();\n}","tryCatchPattern":"catch (PathIOException e) when 'Symlinks unsupported' -> resolve the link target via FileStatus.getSymlink() and setReplication on the target, or skip","preventionTips":["Audit trees for symlinks before recursive -setrep","Apply setrep to target paths, not links","Track which datasets use symlink manifests"],"tags":["setrep","symlink","unsupported-operation","hadoop-shell"],"backgroundTag":"symlink-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}