apache/hadoop · error · HadoopIllegalArgumentException

An XAttr name must be prefixed with user/trusted/security/sy

Error message

An XAttr name must be prefixed with user/trusted/security/system/raw, followed by a '.'

What it means

XAttrHelper.buildXAttr(String, byte[]) splits a fully-qualified extended-attribute name into a namespace (the substring before the first '.') and the attribute name (the rest). Every legal namespace — user, trusted, security, system, raw — is at least three characters, so if the first '.' is missing (indexOf == -1) or appears before index 3, no valid namespace can exist and the name is rejected client-side with HadoopIllegalArgumentException before any RPC.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/XAttrHelper.java:54

  /**
   * Build <code>XAttr</code> from xattr name with prefix.
   */
  public static XAttr buildXAttr(String name) {
    return buildXAttr(name, null);
  }

  /**
   * Build <code>XAttr</code> from name with prefix and value.
   * Name can not be null. Value can be null. The name and prefix
   * are validated.
   * Both name and namespace are case sensitive.
   */
  public static XAttr buildXAttr(String name, byte[] value) {
    Preconditions.checkNotNull(name, "XAttr name cannot be null.");

    final int prefixIndex = name.indexOf(".");
    if (prefixIndex < 3) {// Prefix length is at least 3.
      throw new HadoopIllegalArgumentException("An XAttr name must be " +
          "prefixed with user/trusted/security/system/raw, followed by a '.'");
    } else if (prefixIndex == name.length() - 1) {
      throw new HadoopIllegalArgumentException("XAttr name cannot be empty.");
    }

    NameSpace ns;
    final String prefix = name.substring(0, prefixIndex);
    if (StringUtils.equalsIgnoreCase(prefix, NameSpace.USER.toString())) {
      ns = NameSpace.USER;
    } else if (
        StringUtils.equalsIgnoreCase(prefix, NameSpace.TRUSTED.toString())) {
      ns = NameSpace.TRUSTED;
    } else if (
        StringUtils.equalsIgnoreCase(prefix, NameSpace.SYSTEM.toString())) {
      ns = NameSpace.SYSTEM;
    } else if (
        StringUtils.equalsIgnoreCase(prefix, NameSpace.SECURITY.toString())) {
      ns = NameSpace.SECURITY;

View on GitHub (pinned to 2add963021)

Solutions

1. Prefix the attribute with a supported namespace, e.g. 'user.color' for ordinary client access.
2. Use trusted./security./system./raw. only from privileged callers — they are restricted namespaces.
3. Validate xattr names once (regex '(?i)(user|trusted|security|system|raw)\..+') at your API boundary.

Example fix

// before
dfs.setXAttr(path, "color", Bytes.toBytes("blue")); // no namespace prefix

// after
dfs.setXAttr(path, "user.color", Bytes.toBytes("blue"));

private static final Pattern VALID_XATTR_NAME =
    Pattern.compile("(?i)(user|trusted|security|system|raw)\\..+");

if (name == null || !VALID_XATTR_NAME.matcher(name).matches()) {
  throw new IllegalArgumentException(
      "xattr name must be '<namespace>.<name>' with namespace in "
      + "user/trusted/security/system/raw, got: " + name);
}

try {
  dfs.setXAttr(path, name, value);
} catch (HadoopIllegalArgumentException e) {
  // invalid name format: surface the offending input for the caller to fix
  throw new IllegalArgumentException(
      "Bad xattr name '" + name + "': " + e.getMessage(), e);
}

When it happens

Trigger: setXAttr(path, name, value) or removeXAttr(path, name) with a name that omits the namespace prefix ('color'), contains no dot at all ('color123'), or has a prefix shorter than three characters ('us.x').

Common situations: Applications ported from POSIX xattr APIs where names are unprefixed; tools that assume HDFS applies a default 'user.' namespace (it does not); typos in 'hdfs dfs -setfattr' commands; names built by string concatenation that drops the prefix.

Related errors

• XAttr name cannot be empty.
• XAttr names can not be null or empty.
• Path part {s} from URI {p} is not a valid filename.
• {} doesn't support setXAttr
• {} doesn't support getXAttr

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