apache/hadoop · error · IOException

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

Error message

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

What it means

The inverse branch of the same setXAttr validation: the attribute does not exist and the caller did not pass XAttrSetFlag.CREATE, so the write is rejected. Without CREATE, setting a brand-new name would create metadata the caller did not assert intent to create.

Source

Thrown at hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/RawFileSystem.java:765

      String key = ObjectUtils.pathToKey(qualifiedPath);

      Map<String, String> existedTags = storage.getTags(key);
      if (existedTags.remove(name) != null) {
        storage.putTags(key, existedTags);
      }
    }
  }

  private void validateXAttrFlag(String xAttrName, boolean xAttrExists, EnumSet<XAttrSetFlag> flag)
      throws IOException {
    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

Include CREATE whenever the attribute may legitimately not exist yet: EnumSet.of(CREATE, REPLACE)
Verify the name spelling against listXAttrs(path) before a REPLACE-only write
Re-create the tag explicitly with CREATE if the delete was unintentional

Example fix

// before
fs.setXAttr(path, "user.owner", value, EnumSet.of(XAttrSetFlag.REPLACE)); // absent -> IOException

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

Defensive patterns

Strategy: validation

Validate before calling

boolean exists = fs.listXAttrs(path).contains(name);
if (!exists) {
  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(REPLACE)); }
catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("CREATE flag")) {
    fs.setXAttr(path, name, value, EnumSet.of(CREATE, REPLACE));
  } else throw e;
}

Prevention

Upsert with CREATE|REPLACE unless create-only semantics are required
Verify tag name spelling against listXAttrs before update-only writes
Expect absent tags after out-of-band deletions and re-create them

When it happens

Trigger: fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.REPLACE)) when no tag with that name exists (e.g. it was removed, or a typo in the name).

Common situations: Update-after-delete flows where the tag was cleared between runs; name typos ('user.ownr') making REPLACE target nothing; tags removed out-of-band in the TOS console.

Related errors

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