{"record":{"id":"bfd52d9106f90a14","repo":"apache/hadoop","slug":"flag-does-not-contain-append","errorCode":null,"errorMessage":"${flag} does not contain APPEND","messagePattern":"(.+?) does not contain APPEND","errorType":"exception","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/CreateFlag.java","lineNumber":198,"sourceCode":"            + path.toString()\n            + \". Append or overwrite option must be specified in \" + flag);\n      }\n    } else if (!flag.contains(CREATE)) {\n      throw new FileNotFoundException(\"Non existing file: \" + path.toString()\n          + \". Create option is not specified in \" + flag);\n    }\n  }\n\n  /**\n   * Validate the CreateFlag for the append operation. The flag must contain\n   * APPEND, and cannot contain OVERWRITE.\n   *\n   * @param flag enum set flag.\n   */\n  public static void validateForAppend(EnumSet<CreateFlag> flag) {\n    validate(flag);\n    if (!flag.contains(APPEND)) {\n      throw new HadoopIllegalArgumentException(flag\n          + \" does not contain APPEND\");\n    }\n  }\n}","sourceCodeStart":180,"sourceCodeEnd":202,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/CreateFlag.java#L180-L202","documentation":"CreateFlag.validateForAppend (called by FileSystem.append and FileContext append paths before opening) first runs the generic validate, then requires APPEND to be present, throwing HadoopIllegalArgumentException when it is not. Its purpose is to reject flag sets that came through the append API without actually expressing append semantics.","triggerScenarios":"Calling fs.append(f, bufferSize, progress) / fc.append where the implementation funnels into CreateFlag.validateForAppend with a set lacking APPEND - typically hand-built sets like EnumSet.of(CreateFlag.CREATE) passed into a generic 'open for write' helper that ends up on the append branch, or direct misuse of validateForAppend in tests.","commonSituations":"Unified open-for-write helpers that pick append vs create from flags but always delegate to fs.append(); test code exercising flag validation; copy-pasted flag sets from create paths reused in append paths.","solutions":["Pass EnumSet.of(CreateFlag.APPEND) on the append path (add CREATE as well if you want create-if-missing where supported).","Route by intent in the helper: if (flags.contains(APPEND)) fs.append(...) else fs.create(...) instead of always calling append.","Unit-test both flag shapes through your helper so an invalid combination fails in CI, not in production."],"exampleFix":"// before\npublic FSDataOutputStream openForWrite(Path p, EnumSet<CreateFlag> flags) {\n  return fs.append(p, 4096); // internally validates: flags without APPEND -> throws\n}\n\n// after\npublic FSDataOutputStream openForWrite(Path p, EnumSet<CreateFlag> flags) {\n  return flags.contains(CreateFlag.APPEND)\n      ? fs.append(p, 4096)\n      : fs.create(p, flags.contains(CreateFlag.OVERWRITE));\n}","handlingStrategy":"validation","validationCode":"if (!flags.contains(CreateFlag.APPEND)) {\n  // route to create() instead of append(); CreateFlag.validateForAppend(flags) would throw\n}","typeGuard":"static boolean isAppendCall(EnumSet<CreateFlag> f) {\n  return f.contains(CreateFlag.APPEND);\n}","tryCatchPattern":"try {\n  CreateFlag.validateForAppend(flags);\n} catch (HadoopIllegalArgumentException e) { // '... does not contain APPEND'\n  // correct the flag set before calling fs.append\n}","preventionTips":["Branch on flags.contains(APPEND) before choosing the fs.append vs fs.create call.","Keep append and create flag literals in one constants class so they cannot be mixed up."],"tags":["hadoop","filesystem","create-flag","append","validation","argument-error"],"backgroundTag":"invalid-create-flag","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}