What causes "Perms option is set multiple times" in apache/hadoop?

Pass CreateOpts.perms exactly once

apache/hadoop · error · HadoopIllegalArgumentException

Perms option is set multiple times

Error message

Perms option is set multiple times

What it means

AbstractFileSystem.create requires exactly one CreateOpts.Perms entry; a second one throws HadoopIllegalArgumentException. FileContext.create never triggers this because it rebuilds the option array with CreateOpts.setOpt(CreateOpts.perms(...)) (FileContext.java:692-698), so this fires only for direct AbstractFileSystem.create callers who duplicate the perms option.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java:578

          throw new HadoopIllegalArgumentException(
              "ReplicationFactor option is set multiple times");
        }
        replication = ((CreateOpts.ReplicationFactor) iOpt).getValue();
      } else if (CreateOpts.BytesPerChecksum.class.isInstance(iOpt)) {
        if (bytesPerChecksum != -1) {
          throw new HadoopIllegalArgumentException(
              "BytesPerChecksum option is set multiple times");
        }
        bytesPerChecksum = ((CreateOpts.BytesPerChecksum) iOpt).getValue();
      } else if (CreateOpts.ChecksumParam.class.isInstance(iOpt)) {
        if (checksumOpt != null) {
          throw new  HadoopIllegalArgumentException(
              "CreateChecksumType option is set multiple times");
        }
        checksumOpt = ((CreateOpts.ChecksumParam) iOpt).getValue();
      } else if (CreateOpts.Perms.class.isInstance(iOpt)) {
        if (permission != null) {
          throw new HadoopIllegalArgumentException(
              "Perms option is set multiple times");
        }
        permission = ((CreateOpts.Perms) iOpt).getValue();
      } else if (CreateOpts.Progress.class.isInstance(iOpt)) {
        if (progress != null) {
          throw new HadoopIllegalArgumentException(
              "Progress option is set multiple times");
        }
        progress = ((CreateOpts.Progress) iOpt).getValue();
      } else if (CreateOpts.CreateParent.class.isInstance(iOpt)) {
        if (createParent != null) {
          throw new HadoopIllegalArgumentException(
              "CreateParent option is set multiple times");
        }
        createParent = ((CreateOpts.CreateParent) iOpt).getValue();
      } else {
        throw new HadoopIllegalArgumentException("Unkown CreateOpts of type " +
            iOpt.getClass().getName());

View on GitHub (pinned to 2add963021)

Solutions

Pass CreateOpts.perms exactly once
Replace instead of append: CreateOpts.setOpt(CreateOpts.perms(p), opts)
Prefer FileContext.create, which applies umask and injects/replaces the perms option safely

Example fix

// before
afs.create(f, flag, CreateOpts.perms(FsPermission.getFileDefault()),
    CreateOpts.perms(perm));

// after
afs.create(f, flag, CreateOpts.perms(perm));

Defensive patterns

Strategy: validation

Validate before calling

if (CreateOpts.getOpt(CreateOpts.Perms.class, opts) == null) {
  opts = CreateOpts.setOpt(CreateOpts.perms(FsPermission.getFileDefault()), opts);
}
afs.create(f, flag, opts);

Prevention

Prefer FileContext.create — it injects and umask-applies the permission via setOpt
In direct AbstractFileSystem wrappers, add perms with setOpt (replace), never append
Test wrappers against calls that already carry a Perms option

When it happens

Trigger: Direct afs.create(path, flag, opts) with two CreateOpts.perms(...) entries in opts — e.g. custom framework code that appends a permission default to an array that already contains one.

Common situations: Custom FileContext-like wrappers that add their own default permission instead of using CreateOpts.setOpt; security layers injecting a hardened umask/permission over user opts by append.

Related errors

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