apache/hadoop · error · IOException

Path ${path} is not a symbolic link

Error message

Path ${path} is not a symbolic link

What it means

Identical guard to HdfsLocatedFileStatus: HdfsNamedFileStatus.getSymlink() throws IOException when the entry carries no symlink target bytes (isSymlink() == false). HdfsNamedFileStatus is the non-located variant of HDFS file status; the contract is the same as FileStatus.getSymlink().

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/protocol/HdfsNamedFileStatus.java:108

    super.setOwner(owner);
  }

  @Override
  public void setGroup(String group) {
    super.setOwner(group);
  }

  @Override
  public boolean isSymlink() {
    return uSymlink != null && uSymlink.length > 0;
  }

  @Override
  public Path getSymlink() throws IOException {
    if (isSymlink()) {
      return new Path(DFSUtilClient.bytes2String(getSymlinkInBytes()));
    }
    throw new IOException("Path " + getPath() + " is not a symbolic link");
  }

  @Override
  public void setPermission(FsPermission permission) {
    super.setPermission(permission);
  }

  /**
   * Get the Java UTF8 representation of the local name.
   *
   * @return the local name in java UTF8
   */
  @Override
  public byte[] getLocalNameInBytes() {
    return uPath;
  }

  @Override

View on GitHub (pinned to 2add963021)

Solutions

1. Check isSymlink() before getSymlink().
2. Write a small helper that returns Optional<Path> of the target and use it everywhere.
3. In tests, construct symlink statuses with a non-empty target byte array.

Example fix

// before
Path target = status.getSymlink();

// after
Path target = status.isSymlink() ? status.getSymlink() : null;

static Optional<Path> symlinkTarget(FileStatus st) {
  return (st != null && st.isSymlink()) ? Optional.of(st.getSymlink()) : Optional.empty();
}

try { Path t = st.getSymlink(); }
catch (IOException e) { /* not a symlink — guard with isSymlink() instead */ }

When it happens

Trigger: Calling getSymlink() on statuses returned by getFileStatus/listStatus (non-located path) for a plain file or directory, or on a symlink entry with an empty target array.

Common situations: Shared handling of FileStatus objects where some branches forget the isSymlink() check; unit tests with hand-constructed statuses lacking target bytes.

Related errors

• Path ${path} is not a symbolic link
• Filesystem does not support symlinks!
• Operation not supported
• Source '{srcFile}' and destination '{destFile}' are the same
• iip.getPath() + " is not a file or directory"

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