apache/hadoop · error · IOException

XAttr: {xAttrName} does not exist. The CREATE flag must be s

Error message

XAttr: {xAttrName} does not exist. The CREATE flag must be specified.

What it means

Mirror of the already-exists case in XAttrSetFlag.validate: the attribute does not exist, but the flag set lacks CREATE, so creating it is not authorized. REPLACE-only asserts the attribute exists and will never create it.

Source

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

  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

Use EnumSet.of(CREATE, REPLACE) for upsert behavior
Verify the attribute name matches exactly (namespaces user./trusted./security./raw. are case-sensitive and permission-gated)
If the attribute must pre-exist, create it in a dedicated init step and fail fast when getXAttr returns null

Example fix

// before
fs.setXAttr(path, "user.tag", value, EnumSet.of(XAttrSetFlag.REPLACE));
// IOException: XAttr user.tag does not exist...

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

Defensive patterns

Strategy: fallback

Validate before calling

byte[] existing = fs.getXAttr(path, name);
if (existing == null) {
  fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.CREATE));
} else {
  fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.REPLACE));
}

Try / catch

try {
  fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.REPLACE));
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("does not exist")) {
    fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.CREATE));
  } else {
    throw e;
  }
}

Prevention

Use CREATE|REPLACE for upserts instead of REPLACE alone
Verify exact attribute names (namespace prefix and case) before asserting existence

When it happens

Trigger: setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.REPLACE)) when the attribute was never set, was removed by another client, or the name string does not match the existing attribute exactly.

Common situations: Code assuming an earlier init step created the attribute (ordering bug or race with removeXAttr); attribute name typo or wrong namespace prefix; cleanup scripts removing attributes between runs.

Related errors

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