{"record":{"id":"d4bed0bf0ddf6299","repo":"apache/hadoop","slug":"must-specify-either-create-or-append","errorCode":null,"errorMessage":"Must specify either create or append","messagePattern":"Must specify either create or append","errorType":"exception","errorClass":"HadoopIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java","lineNumber":3986,"sourceCode":"      }\n      if (getFlags().contains(CreateFlag.CREATE) ||\n          getFlags().contains(CreateFlag.OVERWRITE)) {\n        if (isRecursive()) {\n          return dfs.create(getPath(), getPermission(), getFlags(),\n              getBufferSize(), getReplication(), getBlockSize(),\n              getProgress(), getChecksumOpt(), getFavoredNodes(),\n              getEcPolicyName(), getStoragePolicyName());\n        } else {\n          return dfs.createNonRecursive(getPath(), getPermission(), getFlags(),\n              getBufferSize(), getReplication(), getBlockSize(), getProgress(),\n              getChecksumOpt(), getFavoredNodes(), getEcPolicyName(),\n              getStoragePolicyName());\n        }\n      } else if (getFlags().contains(CreateFlag.APPEND)) {\n        return dfs.append(getPath(), getFlags(), getBufferSize(), getProgress(),\n            getFavoredNodes());\n      }\n      throw new HadoopIllegalArgumentException(\n          \"Must specify either create or append\");\n    }\n  }\n\n  /**\n   * Create a HdfsDataOutputStreamBuilder to create a file on DFS.\n   * Similar to {@link #create(Path)}, file is overwritten by default.\n   *\n   * @param path the path of the file to create.\n   * @return A HdfsDataOutputStreamBuilder for creating a file.\n   */\n  @Override\n  public HdfsDataOutputStreamBuilder createFile(Path path) {\n    return new HdfsDataOutputStreamBuilder(this, path).create().overwrite(true);\n  }\n\n  /**\n   * Returns a RemoteIterator which can be used to list all open files","sourceCodeStart":3968,"sourceCodeEnd":4004,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/DistributedFileSystem.java#L3968-L4004","documentation":"Thrown by HdfsDataOutputStreamBuilder.build() in DistributedFileSystem when the builder's CreateFlag set contains neither CREATE/OVERWRITE nor APPEND. The builder API is mode-explicit: you must say whether you are creating or appending before build() dispatches to DFSClient.create/createNonRecursive/append. Hitting it almost always means you used the raw builder() entry point instead of createFile()/appendFile(), which pre-set the flags for you.","triggerScenarios":"Calling ((DistributedFileSystem) fs).builder().path(p)...build() (or FileSystem#createDataOutputStreamBuilder) without ever setting a mode flag; constructing HdfsDataOutputStreamBuilder manually and only setting permission/bufferSize/replication; calling .overwrite(false) on a builder that never had CREATE set (OVERWRITE alone counts, but a builder stripped of flags has none).","commonSituations":"Migrating code from fs.create()/fs.append() to the builder API added in Hadoop 2.8/3.x and forgetting the mode call; copy-pasting a builder chain that omits .overwrite(); generic code that obtains FileSystem.builder() polymorphically and assumes a default mode.","solutions":["Use the factory methods that set the flag for you: dfs.createFile(path).overwrite(true).build() or dfs.appendFile(path).build()","If using the raw builder, add the mode explicitly: builder().path(p).overwrite(true) (sets OVERWRITE) or set CreateFlag.APPEND for append","Audit shared/generic code that calls FileSystem#builder or #createDataOutputStreamBuilder and ensure a mode is set before build()","If you wrap builders, assert getFlags() intersects {CREATE, OVERWRITE, APPEND} before delegating"],"exampleFix":"// before\nFSDataOutputStream out = ((DistributedFileSystem) fs).builder()\n    .path(new Path(\"/data/out.txt\"))\n    .replication((short) 3)\n    .build(); // HadoopIllegalArgumentException: Must specify either create or append\n\n// after\nFSDataOutputStream out = ((DistributedFileSystem) fs)\n    .createFile(new Path(\"/data/out.txt\"))\n    .overwrite(true)\n    .replication((short) 3)\n    .build();","handlingStrategy":"validation","validationCode":"// Prefer factory methods that set the mode flag; guard generic builders:\nDistributedFileSystem dfs = (DistributedFileSystem) fs;\ntry (FSDataOutputStream out = dfs.createFile(path).overwrite(true).build()) {\n  // write\n}\n// If you must use the raw builder, always pair it with a mode:\n// dfs.builder().path(p).overwrite(true)...  or .append()","typeGuard":null,"tryCatchPattern":"try {\n  out = builder.build();\n} catch (HadoopIllegalArgumentException e) {\n  if (e.getMessage().contains(\"Must specify either create or append\")) {\n    throw new IllegalStateException(\"Builder used without create/append mode\", e);\n  }\n  throw e;\n}","preventionTips":["Never call builder().build() without createFile()/appendFile() or an explicit .overwrite()/.create()/.append()","In shared filesystem utility code, branch on requested mode and delegate to createFile() or appendFile() explicitly","Add a unit test that exercises both modes of any builder wrapper you own"],"tags":["hdfs","distributed-filesystem","builder-pattern","file-write","invalid-argument"],"backgroundTag":"missing-required-flag","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}