{"record":{"id":"c02fc326a15f4618","repo":"apache/hadoop","slug":"a-flag-must-be-specified","errorCode":null,"errorMessage":"A flag must be specified.","messagePattern":"A flag must be specified\\.","errorType":"validation","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/XAttrSetFlag.java","lineNumber":56,"sourceCode":"   * Replace a existing xattr.\n   * If the xattr does not exist, exception will be thrown.\n   */\n  REPLACE((short) 0x02);\n\n  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":38,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/XAttrSetFlag.java#L38-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE) for upsert semantics (what the 3-argument setXAttr uses internally)","Pass EnumSet.of(CREATE) when the attribute must be new, or EnumSet.of(REPLACE) when it must already exist","If the flag set comes from configuration/user input, validate it is non-null and non-empty before calling setXAttr"],"exampleFix":"// before\nfs.setXAttr(path, \"user.tag\", value, EnumSet.noneOf(XAttrSetFlag.class));\n// HadoopIllegalArgumentException: A flag must be specified.\n\n// after\nfs.setXAttr(path, \"user.tag\", value,\n    EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE));","handlingStrategy":"validation","validationCode":"EnumSet<XAttrSetFlag> flags = (flagSet == null || flagSet.isEmpty())\n    ? EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE)\n    : flagSet;\nfs.setXAttr(path, name, value, flags);","typeGuard":"static boolean isUsableFlagSet(EnumSet<XAttrSetFlag> flags) {\n  return flags != null && !flags.isEmpty();\n}","tryCatchPattern":"try {\n  fs.setXAttr(path, name, value, flags);\n} catch (HadoopIllegalArgumentException e) {\n  if (e.getMessage().contains(\"flag must be specified\")) {\n    fs.setXAttr(path, name, value,\n        EnumSet.of(XAttrSetFlag.CREATE, XAttrSetFlag.REPLACE));\n  } else {\n    throw e;\n  }\n}","preventionTips":["Default any caller-supplied EnumSet to CREATE|REPLACE instead of noneOf","Remember the 3-argument setXAttr already means CREATE|REPLACE — use it for upserts"],"tags":["xattr","extended-attributes","invalid-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}