apache/hadoop · error · HadoopIllegalArgumentException

Invalid <aclSpec> :

Error message

Invalid <aclSpec> : 

What it means

AclEntry.parseAclEntry(aclStr, includePermission) splits the ACL spec on ':' and validates the token layout of Hadoop ACL entries (e.g. user:foo:rwx, group::r-x, default:user:foo:---). The first guard throws HadoopIllegalArgumentException("Invalid <aclSpec> : ...") when the split yields no usable tokens — effectively an empty or separator-only spec with no type field at all.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/permission/AclEntry.java:271

   *          String representation of an ACL.<br>
   *          Example: "user:foo:rw-"
   * @param includePermission
   *          for setAcl operations this will be true. i.e. Acl should include
   *          permissions.<br>
   *          But for removeAcl operation it will be false. i.e. Acl should not
   *          contain permissions.<br>
   *          Example: "user:foo,group:bar,mask::"
   * @return Returns an {@link AclEntry} object
   */
  public static AclEntry parseAclEntry(String aclStr,
      boolean includePermission) {
    AclEntry.Builder builder = new AclEntry.Builder();
    // Here "::" represent one empty string.
    // StringUtils.getStringCollection() will ignore this.
    String[] split = aclStr.split(":");

    if (split.length == 0) {
      throw new HadoopIllegalArgumentException("Invalid <aclSpec> : " + aclStr);
    }
    int index = 0;
    if ("default".equals(split[0])) {
      // default entry
      index++;
      builder.setScope(AclEntryScope.DEFAULT);
    }

    if (split.length <= index) {
      throw new HadoopIllegalArgumentException("Invalid <aclSpec> : " + aclStr);
    }

    AclEntryType aclType = null;
    try {
      aclType = Enum.valueOf(
          AclEntryType.class, StringUtils.toUpperCase(split[index]));
      builder.setType(aclType);
      index++;

View on GitHub (pinned to 2add963021)

Solutions

1. Validate the spec is non-empty and shape-correct before calling parseAclEntry
2. Fix the upstream variable/substitution so an empty ACL never reaches the parser
3. When generating entries in code, prefer the AclEntry.Builder API over string parsing

Example fix

// before
AclEntry e = AclEntry.parseAclEntry(aclSpec, true);   // aclSpec == "" -> HadoopIllegalArgumentException

// after
if (aclSpec == null || aclSpec.trim().isEmpty()) {
  throw new IllegalArgumentException("aclSpec must not be empty");
}
AclEntry e = AclEntry.parseAclEntry(aclSpec, true);

private static final Pattern ACL_ENTRY =
    Pattern.compile("^(default:)?(user|group|mask|other)(:[^:]*)?(:[rwx-]{1,3})?$",
        Pattern.CASE_INSENSITIVE);

if (aclSpec == null || !ACL_ENTRY.matcher(aclSpec).matches()) {
  throw new IllegalArgumentException("malformed aclSpec: " + aclSpec);
}
AclEntry e = AclEntry.parseAclEntry(aclSpec, includePermission);

catch HadoopIllegalArgumentException from parseAclEntry and surface it to the user/config author with the exact spec and expected format; do not retry the same string.

When it happens

Trigger: Passing an empty string or a spec made only of separators such as ":"; programmatically assembled specs that collapse to empty after filtering (e.g. joining an empty list with ':').

Common situations: Shell/CLI wrappers forwarding unset variables (hdfs dfs -setfacl -m "${ACL}" with ACL empty); config-driven ACL templates where variable substitution produced an empty string; list-handling bugs joining zero entries into a spec.

Related errors

• Invalid type of acl in <aclSpec> :
• value cannot be blank
• ${value} is not in expected format.Expected format is <numbe
• Bad HTML quoting for {}
• User {} can not be added

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