apache/hadoop · error · UnsupportedOperationException

symlinks not supported

Error message

symlinks not supported

What it means

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.

Solutions

  1. Find and remove symlinks under the source root: 'find <src> -type l'.
  2. Or produce a resolved copy with symlinks followed: 'cp -rL <src> <resolved-copy>' and image that.
  3. If symlink support is required, check whether your Hadoop version's fs2img has landed it before upgrading expectations.

Example fix

# before
hadoop fs2img -o file:///img /staging/tree   # contains symlinks

# after
find /staging/tree -type l                    # inspect them
cp -rL /staging/tree /tmp/resolved-tree        # resolve links
hadoop fs2img -o file:///img /tmp/resolved-tree
Defensive patterns

Strategy: validation

Validate before calling

// Pre-scan the source root and fail before imaging if any symlink exists
Files.walk(Paths.get(srcRoot))
     .filter(Files::isSymbolicLink)
     .findFirst()
     .ifPresent(p -> { throw new IllegalStateException("symlink found: " + p + "; fs2img cannot image symlinks"); });

Try / catch

try {
  writer.accept(treePath);   // TreePath.toINode
} catch (UnsupportedOperationException e) {
  if ("symlinks not supported".equals(e.getMessage())) {
    // remove the symlink named in the walk or image a resolved copy (cp -rL)
  }
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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

Appendix: source

Thrown at hadoop-tools/hadoop-fs2img/src/main/java/org/apache/hadoop/hdfs/server/namenode/TreePath.java:108

    if (id < 0) {
      throw new IllegalStateException();
    }
    return id;
  }

  public void accept(long pathId) {
    this.id = pathId;
    i.onAccept(this, id);
  }

  public INode toINode(UGIResolver ugi, BlockResolver blk,
      BlockAliasMap.Writer<FileRegion> out) throws IOException {
    if (stat.isFile()) {
      return toFile(ugi, blk, out);
    } else if (stat.isDirectory()) {
      return toDirectory(ugi);
    } else if (stat.isSymlink()) {
      throw new UnsupportedOperationException("symlinks not supported");
    } else {
      throw new UnsupportedOperationException("Unknown type: " + stat);
    }
  }

  @Override
  public boolean equals(Object other) {
    if (!(other instanceof TreePath)) {
      return false;
    }
    TreePath o = (TreePath) other;
    return getParentId() == o.getParentId()
      && getFileStatus().equals(o.getFileStatus());
  }

  @Override
  public int hashCode() {
    long pId = getParentId() * getFileStatus().hashCode();

View on GitHub (pinned to 2add963021)