apache/hadoop · error · UnsupportedOperationException

{} doesn't support listXAttrs

Error message

{} doesn't support listXAttrs

What it means

FileContext resolves each URI to a per-scheme AbstractFileSystem implementation, and the base class's listXAttrs(Path) is a stub that always throws UnsupportedOperationException, filling the concrete subclass name into the message (e.g. "S3A doesn't support listXAttrs"). Extended attributes are an optional feature: only implementations that override this method (HDFS and WebHDFS) can succeed. Hitting this error means the mounted filesystem for that URI does not implement the xattr API at all - it is not a per-file or permission condition.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java:1451

    throw new UnsupportedOperationException(getClass().getSimpleName()
        + " doesn't support getXAttrs");
  }

  /**
   * Get all of the xattr names for a file or directory.
   * Only the xattr names for which the logged-in user has permissions to view
   * are returned.
   * <p>
   * Refer to the HDFS extended attributes user documentation for details.
   *
   * @param path Path to get extended attributes
   * @return {@literal Map<String, byte[]>} describing the XAttrs of the file
   * or directory
   * @throws IOException raised on errors performing I/O.
   */
  public List<String> listXAttrs(Path path)
          throws IOException {
    throw new UnsupportedOperationException(getClass().getSimpleName()
            + " doesn't support listXAttrs");
  }

  /**
   * Remove 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 remove extended attribute
   * @param name xattr name
   * @throws IOException raised on errors performing I/O.
   */
  public void removeXAttr(Path path, String name) throws IOException {
    throw new UnsupportedOperationException(getClass().getSimpleName()
        + " doesn't support removeXAttr");
  }

View on GitHub (pinned to 2add963021)

Solutions

  1. Read the class name in the message to identify which implementation is actually mounted for the path, and confirm the URI scheme; only hdfs:// and webhdfs:// implement listXAttrs.
  2. Route the operation to HDFS (use an hdfs:// path, or DistributedFileSystem via FileSystem.get, which overrides listXAttrs).
  3. If xattrs are optional for your app, catch UnsupportedOperationException and degrade to "no xattrs" behavior.
  4. For DistCp, drop xattr from the -p attribute list when the destination filesystem does not support it.

Example fix

// before
List<String> names = fc.listXAttrs(path); // throws on s3a:// or file://

// after
List<String> names;
try {
  names = fc.listXAttrs(path);
} catch (UnsupportedOperationException e) {
  names = Collections.emptyList(); // scheme does not implement xattrs
}
Defensive patterns

Strategy: try-catch

Validate before calling

static boolean supportsListXAttrs(FileContext fc, Path probe) throws IOException {
  try {
    fc.listXAttrs(probe);
    return true;
  } catch (UnsupportedOperationException e) {
    return false;
  } catch (IOException e) {
    return true; // supported, but the probe hit an I/O problem
  }
}

Try / catch

try {
  names = fc.listXAttrs(path);
} catch (UnsupportedOperationException e) {
  // optional feature absent on this scheme: degrade, do not retry
  names = Collections.emptyList();
}

Prevention

When it happens

Trigger: Calling FileContext.listXAttrs(path) on a scheme whose AbstractFileSystem keeps the default stub: object stores (s3a, gs, wasb/abfs), ftp/sftp, and the local FileContext backend in versions where it does not override xattr ops. Also triggered indirectly by DistCp run with -p xattr preservation writing to such a target, or by generic FS tooling that enumerates xattrs for every path.

Common situations: Application code written and tested against HDFS is repointed at an object store or file:// (unit tests, local IDE runs, fs.defaultFS change), and the xattr calls that worked on HDFS now throw. Metadata stored in user.* xattrs (labels, lineage, Ranger tags) has no equivalent on the new store.

Related errors

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