{"record":{"id":"3ec3b88b5a4ce237","repo":"apache/hadoop","slug":"xattr-xattrname-already-exists-the-replace-fla","errorCode":null,"errorMessage":"XAttr: {xAttrName} already exists. The REPLACE flag must be specified.","messagePattern":"XAttr: (.+?) already exists\\. The REPLACE flag must be specified\\.","errorType":"validation","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/XAttrSetFlag.java","lineNumber":61,"sourceCode":"  private final short flag;\n\n  private XAttrSetFlag(short flag) {\n    this.flag = flag;\n  }\n\n  short getFlag() {\n    return flag;\n  }\n\n  public static void validate(String xAttrName, boolean xAttrExists,\n      EnumSet<XAttrSetFlag> flag) throws IOException {\n    if (flag == null || flag.isEmpty()) {\n      throw new HadoopIllegalArgumentException(\"A flag must be specified.\");\n    }\n\n    if (xAttrExists) {\n      if (!flag.contains(REPLACE)) {\n        throw new IOException(\"XAttr: \" + xAttrName +\n            \" already exists. The REPLACE flag must be specified.\");\n      }\n    } else {\n      if (!flag.contains(CREATE)) {\n        throw new IOException(\"XAttr: \" + xAttrName +\n            \" does not exist. The CREATE flag must be specified.\");\n      }\n    }\n  }\n}\n","sourceCodeStart":43,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/XAttrSetFlag.java#L43-L72","documentation":"XAttrSetFlag.validate throws this IOException in POSIX-setxattr style: the named extended attribute already exists on the target, but the flag set does not include REPLACE, so overwriting is not authorized. The attribute name in the message is the fully qualified name (user.*, trusted.*, etc.).","triggerScenarios":"setXAttr(path, name, value, EnumSet.of(CREATE)) when 'name' is already stored on the path; re-running an initializer that uses CREATE-only after a previous successful run.","commonSituations":"Idempotent metadata writers re-running after partial job failure; two clients racing to initialize the same attribute (one wins with CREATE, the other loses); migration jobs that re-tag existing files.","solutions":["Use EnumSet.of(CREATE, REPLACE) when either state is acceptable (upsert)","Check existence first with fs.getXAttr(path, name) != null and pick CREATE vs REPLACE (still subject to races)","removeXAttr(path, name) before setting with CREATE","Catch the IOException and retry with REPLACE if the attribute was created concurrently"],"exampleFix":"// before\nfs.setXAttr(path, \"user.tag\", value, EnumSet.of(XAttrSetFlag.CREATE));\n// IOException: XAttr user.tag already exists...\n\n// after\nfs.setXAttr(path, \"user.tag\", value,\n    EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE));","handlingStrategy":"fallback","validationCode":"byte[] existing = fs.getXAttr(path, name);\nEnumSet<XAttrSetFlag> flags = (existing != null)\n    ? EnumSet.of(XAttrSetFlag.REPLACE)\n    : EnumSet.of(XAttrSetFlag.CREATE);\nfs.setXAttr(path, name, value, flags); // still racy between get and set","typeGuard":null,"tryCatchPattern":"try {\n  fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.CREATE));\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"already exists\")) {\n    fs.setXAttr(path, name, value, EnumSet.of(XAttrSetFlag.REPLACE));\n  } else {\n    throw e;\n  }\n}","preventionTips":["Use CREATE|REPLACE when either state is acceptable","For initialize-once attributes, tolerate the 'already exists' path as success in retries"],"tags":["xattr","extended-attributes","already-exists"],"backgroundTag":"already-exists","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}