apache/hadoop · error · HadoopIllegalArgumentException

${flag} does not specify any options

Error message

${flag} does not specify any options

What it means

CreateFlag.validate(EnumSet<CreateFlag>) rejects a null or empty flag set with HadoopIllegalArgumentException. Every create/append path (FileSystem.create with EnumSet, FileContext.create, builder APIs, HarFileSystem, FilterFs.createInternal) funnels through this validation, because with no flags the filesystem cannot know whether you intend create, overwrite, or append.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/CreateFlag.java:151

  private final short mode;

  private CreateFlag(short mode) {
    this.mode = mode;
  }

  short getMode() {
    return mode;
  }
  
  /**
   * Validate the CreateFlag and throw exception if it is invalid
   * @param flag set of CreateFlag
   * @throws HadoopIllegalArgumentException if the CreateFlag is invalid
   */
  public static void validate(EnumSet<CreateFlag> flag) {
    if (flag == null || flag.isEmpty()) {
      throw new HadoopIllegalArgumentException(flag
          + " does not specify any options");
    }
    final boolean append = flag.contains(APPEND);
    final boolean overwrite = flag.contains(OVERWRITE);
    
    // Both append and overwrite is an error
    if (append && overwrite) {
      throw new HadoopIllegalArgumentException(
          flag + "Both append and overwrite options cannot be enabled.");
    }
  }
  
  /**
   * Validate the CreateFlag for create operation
   * @param path Object representing the path; usually String or {@link Path}
   * @param pathExists pass true if the path exists in the file system
   * @param flag set of CreateFlag
   * @throws IOException on error

View on GitHub (pinned to 2add963021)

Solutions

1. Always seed the set with the primary intent: EnumSet.of(CreateFlag.CREATE) for new files, or EnumSet.of(CreateFlag.CREATE, CreateFlag.OVERWRITE) to clobber.
2. Build flags in one place from booleans and assert non-empty before the fs call: Preconditions.checkArgument(!flags.isEmpty()).
3. Call CreateFlag.validate(flags) yourself before touching the filesystem to get the failure at the construction site rather than deep in the fs stack.

Example fix

// before
EnumSet<CreateFlag> flags = EnumSet.noneOf(CreateFlag.class);
if (overwrite) flags.add(CreateFlag.OVERWRITE);
fs.create(path, perms, flags, 4096, (short)1, 1<<26, null); // empty when overwrite=false

// after
EnumSet<CreateFlag> flags = overwrite
    ? EnumSet.of(CreateFlag.CREATE, CreateFlag.OVERWRITE)
    : EnumSet.of(CreateFlag.CREATE);
fs.create(path, perms, flags, 4096, (short)1, 1<<26, null);

if (flags == null || flags.isEmpty()) {
  throw new IllegalArgumentException("write mode required: CREATE and/or OVERWRITE/APPEND");
}

static EnumSet<CreateFlag> normalizedFlags(boolean overwrite) {
  return overwrite ? EnumSet.of(CreateFlag.CREATE, CreateFlag.OVERWRITE)
                   : EnumSet.of(CreateFlag.CREATE);
}

try {
  fs.create(path, perms, flags, buf, rep, block, null);
} catch (HadoopIllegalArgumentException e) { // '... does not specify any options'
  // rebuild flags with an explicit primary intent and retry
}

When it happens

Trigger: Passing EnumSet.noneOf(CreateFlag.class) (or a set that ended up empty after conditional adds like flags.add(x) inside a skipped if) to fs.create(f, perms, flags, ...) / fc.create(f, EnumSet<CreateFlag>, ...) or calling CreateFlag.validate directly with an empty set.

Common situations: Flag sets built dynamically: EnumSet<CreateFlag> flags = EnumSet.noneOf(...); if (overwrite) flags.add(OVERWRITE); ... and the branch conditions are all false, leaving it empty; refactoring removes the flag.add(CREATE) call; test helpers constructing flags from a config value that is unset.

Related errors

• ${flag} does not contain APPEND
• ${flag}Both append and overwrite options cannot be enabled.
• relative paths not allowed:{path}
• The source {src} and destination {dst} are the same
• File already exists: ${path}. Append or overwrite option mus

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