apache/hadoop · error · HadoopIllegalArgumentException

Missing <acl_spec> entry

Error message

Missing <acl_spec> entry

What it means

Setfacl.processOptions throws HadoopIllegalArgumentException('Missing <acl_spec> entry') when AclEntry.parseAclSpec on the first operand returns an empty list. parseAclSpec tokenizes on commas (StringUtils.getStringCollection), so an empty string or a string of only delimiters produces zero entries — the operand was present but carried no ACL data.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/shell/AclCommands.java:220

          || (oneRemoveOption && oneModifyOption)
          || (setOption && (oneRemoveOption || oneModifyOption))) {
        throw new HadoopIllegalArgumentException(
            "Specified flags contains both remove and modify flags");
      }

      // Only -m, -x and --set expects <acl_spec>
      if (oneModifyOption || setOption) {
        if (args.isEmpty()) {
          throw new HadoopIllegalArgumentException(
              "Missing arguments: <acl_spec> <path>");
        }
        if (args.size() < 2) {
          throw new HadoopIllegalArgumentException(
              "Missing either <acl_spec> or <path>");
        }
        aclEntries = AclEntry.parseAclSpec(args.removeFirst(), !cf.getOpt("x"));
        if (aclEntries.isEmpty()) {
          throw new HadoopIllegalArgumentException(
              "Missing <acl_spec> entry");
        }
      }

      if (args.isEmpty()) {
        throw new HadoopIllegalArgumentException("<path> is missing");
      }
      if (args.size() > 1) {
        throw new HadoopIllegalArgumentException("Too many arguments");
      }

      if (!hasExpectedOptions) {
        throw new HadoopIllegalArgumentException(
            "Expected one of -b, -k, -m, -x or --set options");
      }
      // In recursive mode, save a separate list of just the access ACL entries.
      // Only directories may have a default ACL.  When a recursive operation
      // encounters a file under the specified path, it must pass only the

View on GitHub (pinned to 2add963021)

Solutions

1. Provide at least one well-formed entry: user:tom:r--, group::r-x for -m/--set, or user:tom for -x (no permissions in remove mode).
2. Validate the spec is non-empty and matches the entry grammar before invoking the command.

Example fix

# before
SPEC=""
hadoop fs -setfacl -m "$SPEC" /data

# after
SPEC='user:tom:r--'
hadoop fs -setfacl -m "$SPEC" /data

case "$SPEC" in
  ''|*[!a-zA-Z0-9_:,-]*) echo "invalid acl_spec: '$SPEC'" >&2; exit 2;;
esac
hadoop fs -setfacl -m "$SPEC" /data

When it happens

Trigger: 'hadoop fs -setfacl -m "" /path' (empty spec string) or 'hadoop fs -setfacl -m "," /path' (delimiters only); an unset spec variable quoted into the command as an empty string while the path is still present.

Common situations: Script variables that are defined but empty; templating/quoting bugs that pass '' as the spec; whitespace-only specs after trimming elsewhere.

Related errors

• Specified flags contains both remove and modify flags
• Missing arguments: <acl_spec> <path>
• Missing either <acl_spec> or <path>
• Expected one of -b, -k, -m, -x or --set options
• <path> is missing

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