apache/hadoop · error · UnsupportedOperationException

{} doesn't support setXAttr

Error message

{} doesn't support setXAttr

What it means

FileSystem.setXAttr(Path, String, byte[], EnumSet<XAttrSetFlag>) is optional; the base class throws UnsupportedOperationException with getClass().getSimpleName() + " doesn't support setXAttr". Extended attributes are an HDFS feature (namespaces like user.* and trusted.*); implemented by DistributedFileSystem, WebHdfsFileSystem, HttpFSFileSystem and pass-throughs. Local filesystem and S3A/GCS-style connectors throw. Note: on HDFS, even with the override, server-side rules (namespace restrictions) produce separate IOExceptions — this UOE is purely about the client implementation lacking the feature.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java:3267

  /**
   * Set an xattr of a file or directory.
   * The name must be prefixed with the namespace followed by ".". For example,
   * "user.attr".
   * <p>
   * Refer to the HDFS extended attributes user documentation for details.
   *
   * @param path Path to modify
   * @param name xattr name.
   * @param value xattr value.
   * @param flag xattr set flag
   * @throws IOException IO failure
   * @throws UnsupportedOperationException if the operation is unsupported
   *         (default outcome).
   */
  public void setXAttr(Path path, String name, byte[] value,
      EnumSet<XAttrSetFlag> flag) throws IOException {
    throw new UnsupportedOperationException(getClass().getSimpleName()
        + " doesn't support setXAttr");
  }

  /**
   * Get an xattr name and value for a file or directory.
   * The name must be prefixed with the namespace followed by ".". For example,
   * "user.attr".
   * <p>
   * Refer to the HDFS extended attributes user documentation for details.
   *
   * @param path Path to get extended attribute
   * @param name xattr name.
   * @return byte[] xattr value.
   * @throws IOException IO failure
   * @throws UnsupportedOperationException if the operation is unsupported
   *         (default outcome).
   */
  public byte[] getXAttr(Path path, String name) throws IOException {

View on GitHub (pinned to 2add963021)

Solutions

  1. Probe fs.hasPathCapability(path, CommonPathCapabilities.FS_XATTRS) before tagging
  2. On stores without xattrs, persist metadata in sidecar files (path + '.meta') or an external catalog
  3. distcp: drop xattr (and acl) preservation for non-HDFS destinations
  4. Catch UnsupportedOperationException and skip tagging with a warn — never retry the call

Example fix

// before
fs.setXAttr(path, "user.provenance", value,
    EnumSet.of(XAttrSetFlag.CREATE));
// throws on LocalFileSystem/S3A

// after
if (fs.hasPathCapability(path, CommonPathCapabilities.FS_XATTRS)) {
  fs.setXAttr(path, "user.provenance", value, EnumSet.of(XAttrSetFlag.CREATE));
} else {
  writeSidecar(path, "provenance", value);
}
Defensive patterns

Strategy: try-catch

Validate before calling

import org.apache.hadoop.fs.CommonPathCapabilities;

if (fs.hasPathCapability(path, CommonPathCapabilities.FS_XATTRS)) {
  fs.setXAttr(path, "user.tag", value, EnumSet.of(XAttrSetFlag.CREATE));
} else {
  writeSidecar(path, "tag", value);
}

Type guard

static boolean supportsXattrWrite(FileSystem fs) {
  return fs instanceof DistributedFileSystem
      || fs instanceof WebHdfsFileSystem;
}

Try / catch

try {
  fs.setXAttr(path, name, value, flags);
} catch (UnsupportedOperationException e) {
  // class in e.getMessage() has no xattr storage: write sidecar metadata instead
}

Prevention

When it happens

Trigger: Calling fs.setXAttr(path, "user.tag", value, flags) on file://, s3a://, gs://, har:// or a custom FileSystem; metadata-tagging frameworks (Ranger tag sync, encryption-zone tooling, app-level annotations) attaching attributes unconditionally.

Common situations: Tagging/policy pipelines run in local tests or against object stores; distcp -p preserving xattrs to a non-HDFS target; migrations off HDFS where tooling still stamps attributes.

Related errors

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