{"record":{"id":"c36749f1c7d731a4","repo":"apache/hadoop","slug":"symlinks-not-supported-c36749","errorCode":null,"errorMessage":"symlinks not supported","messagePattern":"symlinks not supported","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-fs2img/src/main/java/org/apache/hadoop/hdfs/server/namenode/TreePath.java","lineNumber":108,"sourceCode":"    if (id < 0) {\n      throw new IllegalStateException();\n    }\n    return id;\n  }\n\n  public void accept(long pathId) {\n    this.id = pathId;\n    i.onAccept(this, id);\n  }\n\n  public INode toINode(UGIResolver ugi, BlockResolver blk,\n      BlockAliasMap.Writer<FileRegion> out) throws IOException {\n    if (stat.isFile()) {\n      return toFile(ugi, blk, out);\n    } else if (stat.isDirectory()) {\n      return toDirectory(ugi);\n    } else if (stat.isSymlink()) {\n      throw new UnsupportedOperationException(\"symlinks not supported\");\n    } else {\n      throw new UnsupportedOperationException(\"Unknown type: \" + stat);\n    }\n  }\n\n  @Override\n  public boolean equals(Object other) {\n    if (!(other instanceof TreePath)) {\n      return false;\n    }\n    TreePath o = (TreePath) other;\n    return getParentId() == o.getParentId()\n      && getFileStatus().equals(o.getFileStatus());\n  }\n\n  @Override\n  public int hashCode() {\n    long pId = getParentId() * getFileStatus().hashCode();","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-fs2img/src/main/java/org/apache/hadoop/hdfs/server/namenode/TreePath.java#L90-L126","documentation":"TreePath.toINode() maps each walked FileStatus to an INode: files and directories are handled, but a symlink hits stat.isSymlink() and throws UnsupportedOperationException. fs2img (this code even carries a 'TODO symlinks' in FSTreeWalk) cannot represent symbolic links in the generated fsimage, so any symlink anywhere under the walked root aborts image generation when that entry is converted.","triggerScenarios":"The source tree passed to 'hadoop fs2img' contains a symbolic link; the walk reaches it and toINode() takes the isSymlink() branch. Common with trees mirroring Unix-style layouts (conf dirs with versioned links).","commonSituations":"Imaging a local FS tree containing /etc-style or node_modules-style symlinks; a staging directory assembled with 'ln -s' shortcuts; packaging directories with 'current' -> versioned links.","solutions":["Find and remove symlinks under the source root: 'find <src> -type l'.","Or produce a resolved copy with symlinks followed: 'cp -rL <src> <resolved-copy>' and image that.","If symlink support is required, check whether your Hadoop version's fs2img has landed it before upgrading expectations."],"exampleFix":"# before\nhadoop fs2img -o file:///img /staging/tree   # contains symlinks\n\n# after\nfind /staging/tree -type l                    # inspect them\ncp -rL /staging/tree /tmp/resolved-tree        # resolve links\nhadoop fs2img -o file:///img /tmp/resolved-tree","handlingStrategy":"validation","validationCode":"// Pre-scan the source root and fail before imaging if any symlink exists\nFiles.walk(Paths.get(srcRoot))\n     .filter(Files::isSymbolicLink)\n     .findFirst()\n     .ifPresent(p -> { throw new IllegalStateException(\"symlink found: \" + p + \"; fs2img cannot image symlinks\"); });","typeGuard":null,"tryCatchPattern":"try {\n  writer.accept(treePath);   // TreePath.toINode\n} catch (UnsupportedOperationException e) {\n  if (\"symlinks not supported\".equals(e.getMessage())) {\n    // remove the symlink named in the walk or image a resolved copy (cp -rL)\n  }\n}","preventionTips":["Run 'find <src> -type l' as a preflight before every fs2img run.","Assemble staging trees without 'ln -s' shortcuts, or resolve them with cp -rL before imaging."],"tags":["fs2img","symlink","unsupported-file-type","fsimage","treewalk"],"backgroundTag":"unsupported-file-type","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}