apache/hadoop · error · BadAclFormatException

ACL '{}' not of expected form scheme:id:perm

Error message

ACL '{}' not of expected form scheme:id:perm

What it means

When ZKUtil splits a ZooKeeper ACL string into comma-separated entries and builds ACL objects, each entry must contain at least two colons so it can be split into scheme:id:perm (the code requires firstColon != -1, lastColon != -1, and firstColon != lastColon, which guarantees a non-empty perm segment). An entry with zero or exactly one colon — like "world:anyone" or "digest:user" — throws BadAclFormatException with this message.

Source

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

   * @return ACL list
   * @throws BadAclFormatException if an ACL is invalid
   */
  public static List<ACL> parseACLs(String aclString) throws
      BadAclFormatException {
    List<ACL> acl = Lists.newArrayList();
    if (aclString == null) {
      return acl;
    }
    
    List<String> aclComps = Lists.newArrayList(
        Splitter.on(',').omitEmptyStrings().trimResults()
        .split(aclString));
    for (String a : aclComps) {
      // from ZooKeeperMain private method
      int firstColon = a.indexOf(':');
      int lastColon = a.lastIndexOf(':');
      if (firstColon == -1 || lastColon == -1 || firstColon == lastColon) {
        throw new BadAclFormatException(
            "ACL '" + a + "' not of expected form scheme:id:perm");
      }

      ACL newAcl = new ACL();
      newAcl.setId(new Id(a.substring(0, firstColon), a.substring(
          firstColon + 1, lastColon)));
      newAcl.setPerms(getPermFromString(a.substring(lastColon + 1)));
      acl.add(newAcl);
    }
    
    return acl;
  }
  
  /**
   * Parse a comma-separated list of authentication mechanisms. Each
   * such mechanism should be of the form 'scheme:auth' -- the same
   * syntax used for the 'addAuth' command in the ZK CLI.
   * 

View on GitHub (pinned to 2add963021)

Solutions

1. Give every ACL entry all three parts: "world:anyone:rwcda" or "sasl:zkcli:rwdca".
2. Check the config key consumed by ZKUtil (e.g. the YARN registry ZooKeeper ACL property) for truncated entries.
3. Pre-validate with a matcher such as ^[^:]+:[^:]+:[rwcda]+$ per comma-separated entry.
4. Catch BadAclFormatException during config parsing and log which entry is malformed.

Example fix

// before
List<ACL> acls = ZKUtil.stringToACLs("world:anyone");
// throws: ACL 'world:anyone' not of expected form scheme:id:perm

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

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

static void validateAclEntries(String aclString) {
  for (String entry : aclString.split(",")) {
    if (!ACL_ENTRY.matcher(entry).matches()) {
      throw new IllegalArgumentException(
          "ACL entry '" + entry + "' must be scheme:id:perm");
    }
  }
}

validateAclEntries(aclConf); // before ZKUtil.stringToACLs

try {
  acls = ZKUtil.stringToACLs(aclString);
} catch (ZKUtil.BadAclFormatException e) {
  LOG.error("Malformed ACL entry in config; expected scheme:id:perm", e);
  failStartup(e);
}

When it happens

Trigger: ZKUtil.stringToACLs("world:anyone") (perm missing); "sasl:hdfs" in a hadoop.registry-style ACL config; "world:anyone:" (colon at the end still means firstColon == lastColon); entries produced by string concatenation that dropped the perm segment.

Common situations: Manually edited ZooKeeper ACL configuration where the permissions part was omitted; converting documentation examples like 'scheme:id' to config; scripts that build ACL strings from optional fields that turn out empty.

Related errors

• Invalid permission '{}' in permission string '{}'
• 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/ad939d5f7740a59e. Report an issue: GitHub.