apache/hadoop · error · BadAclFormatException

Invalid permission '{}' in permission string '{}'

Error message

Invalid permission '{}' in permission string '{}'

What it means

ZKUtil's ACL parser (used when converting ZooKeeper ACL configuration strings into org.apache.zookeeper.data.ACL objects) parses only the perm segment letters r, w, c, d, a (READ, WRITE, CREATE, DELETE, ADMIN). Any other character in the permission part of an entry triggers BadAclFormatException with this message, which extends HadoopIllegalArgumentException.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/ZKUtil.java:65

      char c = permString.charAt(i); 
      switch (c) {
      case 'r':
        perm |= ZooDefs.Perms.READ;
        break;
      case 'w':
        perm |= ZooDefs.Perms.WRITE;
        break;
      case 'c':
        perm |= ZooDefs.Perms.CREATE;
        break;
      case 'd':
        perm |= ZooDefs.Perms.DELETE;
        break;
      case 'a':
        perm |= ZooDefs.Perms.ADMIN;
        break;
      default:
        throw new BadAclFormatException(
            "Invalid permission '" + c + "' in permission string '" +
            permString + "'");
      }
    }
    return perm;
  }

  /**
   * Helper method to remove a subset of permissions (remove) from a
   * given set (perms).
   * @param perms The permissions flag to remove from. Should be an OR of a
   *              some combination of {@link ZooDefs.Perms}
   * @param remove The permissions to be removed. Should be an OR of a
   *              some combination of {@link ZooDefs.Perms}
   * @return A permissions flag that is an OR of {@link ZooDefs.Perms}
   * present in perms and not present in remove
   */
  public static int removeSpecificPerms(int perms, int remove) {

View on GitHub (pinned to 2add963021)

Solutions

1. Use only the letters r, w, c, d, a in the permission segment, e.g. "world:anyone:rwcda".
2. Fix the config value (typically the ZooKeeper ACL property consumed by ZKUtil) to use letter codes.
3. Pre-validate each comma-separated entry with a regex like ^[^:]+:[^:]*:[rwcda]+$ before passing it to ZKUtil.
4. Catch BadAclFormatException at config load and report the malformed ACL entry.

Example fix

// before
List<ACL> acls = ZKUtil.stringToACLs("world:anyone:read");
// throws: Invalid permission 'e' in permission string 'read'

// after
List<ACL> acls = ZKUtil.stringToACLs("world:anyone:r");

private static final Pattern ACL_ENTRY =
    Pattern.compile("^[^:,]+:[^:,]*:[rwcda]*$");

static void validateAclString(String acl) {
  for (String entry : acl.split(",")) {
    if (!ACL_ENTRY.matcher(entry).matches()) {
      throw new IllegalArgumentException(
          "Bad ACL entry '" + entry + "': perms may only contain r,w,c,d,a");
    }
  }
}

validateAclString(aclConf); // before ZKUtil.stringToACLs(aclConf)

try {
  List<ACL> acls = ZKUtil.stringToACLs(aclConf);
} catch (ZKUtil.BadAclFormatException e) {
  throw new ConfigurationException(
      "Invalid ZooKeeper ACL config: " + e.getMessage(), e);
}

When it happens

Trigger: ZKUtil.stringToACLs / parseAcls with entries like "world:anyone:rwxa" ('x' invalid), "sasl:hdfs:read" ('read' is not a letter sequence the switch understands — 'r' works, 'e' from 'read' then fails), or "world:anyone:*"; reached indirectly from services parsing ZooKeeper ACL config values (e.g. YARN registry 'hadoop.registry.zk.acl').

Common situations: Writing descriptive permissions ('read', 'write', 'all') instead of the letter codes; copying ZooKeeper docs that show 'cdrwa' (valid) but mistyping a letter; a trailing character from manual config edits; using 'x' for execute by analogy with POSIX modes.

Related errors

• ACL '{}' not of expected form scheme:id:perm
• Auth '{}' not of expected form scheme:auth
• Target address cannot be null. (configuration property '${co
• Does not contain a valid host:port authority: ${target} (con
• Percentage " + percentage + " must be greater than or equal

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