What causes "Storage policy are not supported on symlinks" in apache/hadoop?

Query the policy of the link's target file/directory (resolve the path first)

apache/hadoop · error · UnsupportedOperationException

Storage policy are not supported on symlinks

Error message

Storage policy are not supported on symlinks

What it means

INodeSymlink.getStoragePolicyID unconditionally throws UnsupportedOperationException("Storage policy are not supported on symlinks"). Querying or applying a storage policy resolves the inode's policy id; because block placement applies to the target's blocks, a symlink inode has no policy of its own and this getter refuses rather than returning a bogus id.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/INodeSymlink.java:144

  @Override
  final XAttrFeature getXAttrFeature(int snapshotId) {
    throw new UnsupportedOperationException("XAttrs are not supported on symlinks");
  }
  
  @Override
  public void removeXAttrFeature() {
    throw new UnsupportedOperationException("XAttrs are not supported on symlinks");
  }
  
  @Override
  public void addXAttrFeature(XAttrFeature f) {
    throw new UnsupportedOperationException("XAttrs are not supported on symlinks");
  }

  @Override
  public byte getStoragePolicyID() {
    throw new UnsupportedOperationException(
        "Storage policy are not supported on symlinks");
  }

  @Override
  public byte getLocalStoragePolicyID() {
    throw new UnsupportedOperationException(
        "Storage policy are not supported on symlinks");
  }
}

View on GitHub (pinned to 2add963021)

Solutions

Query the policy of the link's target file/directory (resolve the path first)
Skip symlinks in policy-audit scripts
When writing NN-side code, resolve the INode to a file before consulting getStoragePolicyID

Example fix

# before
hdfs storagepolicies -getStoragePolicy -path /data/link-to-file
# -> UnsupportedOperationException: Storage policy are not supported on symlinks

# after
TARGET=$(readlink -f <(hdfs dfs -ls /data/link-to-file))  # or resolve manually
hdfs storagepolicies -getStoragePolicy -path /data/real/file

Defensive patterns

Strategy: type-guard

Validate before calling

FileStatus st = fs.getFileStatus(p);
if (st.isSymlink()) {
  p = st.getSymlink();  // policy lives on the target
}
// then: hdfs storagepolicies -getStoragePolicy -path <resolved>

Type guard

boolean hasStoragePolicy(FileSystem fs, Path p) throws IOException {
  return !fs.getFileStatus(p).isSymlink();
}

Try / catch

catch (UnsupportedOperationException e) {
  if (e.getMessage() != null && e.getMessage().contains("Storage policy")) {
    skip(path);  // symlinks carry no policy; query the target instead
  } else { throw e; }
}

Prevention

Resolve links before policy queries in audit scripts
In NN-internal code, never call getStoragePolicyID on an unresolved INodeSymlink
Keep policy tooling aligned with the fact that placement applies to target blocks

When it happens

Trigger: `hdfs storagepolicies -getStoragePolicy -path <symlink>`; internal block-placement or mover logic that asks a symlink inode (instead of the resolved file) for its storage policy id.

Common situations: Administrators checking policies across user directories that contain symlinks; scripts iterating `hdfs fsck`/storagepolicies output; SPS or mover flows encountering unresolved links.

Related errors

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