apache/hadoop · error · HadoopIllegalArgumentException

A flag must be specified.

Error message

A flag must be specified.

What it means

XAttrSetFlag.validate rejects a setXAttr call that carries no flags. Hadoop extended attributes are set via FileSystem.setXAttr(path, name, value, EnumSet<XAttrSetFlag>) and the flag set must be non-null and non-empty: it is the caller's job to declare whether the attribute may be created, replaced, or both. The 3-argument setXAttr(path, name, value) form avoids this by internally using CREATE|REPLACE.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/XAttrSetFlag.java:56

   * Replace a existing xattr.
   * If the xattr does not exist, exception will be thrown.
   */
  REPLACE((short) 0x02);

  private final short flag;

  private XAttrSetFlag(short flag) {
    this.flag = flag;
  }

  short getFlag() {
    return flag;
  }

  public static void validate(String xAttrName, boolean xAttrExists,
      EnumSet<XAttrSetFlag> flag) throws IOException {
    if (flag == null || flag.isEmpty()) {
      throw new HadoopIllegalArgumentException("A flag must be specified.");
    }

    if (xAttrExists) {
      if (!flag.contains(REPLACE)) {
        throw new IOException("XAttr: " + xAttrName +
            " already exists. The REPLACE flag must be specified.");
      }
    } else {
      if (!flag.contains(CREATE)) {
        throw new IOException("XAttr: " + xAttrName +
            " does not exist. The CREATE flag must be specified.");
      }
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Pass EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE) for upsert semantics (what the 3-argument setXAttr uses internally)
2. Pass EnumSet.of(CREATE) when the attribute must be new, or EnumSet.of(REPLACE) when it must already exist
3. If the flag set comes from configuration/user input, validate it is non-null and non-empty before calling setXAttr

Example fix

// before
fs.setXAttr(path, "user.tag", value, EnumSet.noneOf(XAttrSetFlag.class));
// HadoopIllegalArgumentException: A flag must be specified.

// after
fs.setXAttr(path, "user.tag", value,
    EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE));

EnumSet<XAttrSetFlag> flags = (flagSet == null || flagSet.isEmpty())
    ? EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE)
    : flagSet;
fs.setXAttr(path, name, value, flags);

static boolean isUsableFlagSet(EnumSet<XAttrSetFlag> flags) {
  return flags != null && !flags.isEmpty();
}

try {
  fs.setXAttr(path, name, value, flags);
} catch (HadoopIllegalArgumentException e) {
  if (e.getMessage().contains("flag must be specified")) {
    fs.setXAttr(path, name, value,
        EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE));
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling setXAttr(path, name, value, null) or setXAttr(path, name, value, EnumSet.noneOf(XAttrSetFlag.class)); forwarding a user-supplied EnumSet that defaulted to an empty set.

Common situations: Generic metadata wrappers that accept an EnumSet parameter which callers leave empty; refactors that dropped the flag argument; porting code from the 3-arg form and assuming flags are optional.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• {} doesn't support setXAttr
• {} doesn't support getXAttr
• {} doesn't support getXAttrs
• {} doesn't support setXAttr
• XAttr: {xAttrName} already exists. The REPLACE flag must be

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