juicedata/juicefs · error · AclException

Invalid ACL: ACL has " + defaultEntries.size() + " default e

Error message

Invalid ACL: ACL has " + defaultEntries.size() + " default entries, which exceeds maximum of " + MAX_ENTRIES + ".

What it means

checkMaxEntries' limit check for the DEFAULT scope: when a default ACL (inheritance ACL on a directory) contains more than MAX_ENTRIES entries it is rejected. Same rationale as the access-scope cap — bounded metadata size per inode.

Source

Thrown at sdk/java/src/main/java/io/juicefs/utils/AclTransformation.java:204

      }
      if (!scopedEntries.getDefaultEntries().isEmpty()) {
        AclEntry defaultEntryKey = new AclEntry.Builder().setScope(DEFAULT).setType(type).build();
        if (Collections.binarySearch(scopedEntries.getDefaultEntries(), defaultEntryKey, ACL_ENTRY_COMPARATOR) < 0) {
          throw new AclException("Invalid default ACL: the user, group and other entries are required.");
        }
      }
    }
    return Collections.unmodifiableList(aclBuilder);
  }

  private static void checkMaxEntries(ScopedAclEntries scopedEntries) throws AclException {
    List<AclEntry> accessEntries = scopedEntries.getAccessEntries();
    List<AclEntry> defaultEntries = scopedEntries.getDefaultEntries();
    if (accessEntries.size() > MAX_ENTRIES) {
      throw new AclException("Invalid ACL: ACL has " + accessEntries.size() + " access entries, which exceeds maximum of " + MAX_ENTRIES + ".");
    }
    if (defaultEntries.size() > MAX_ENTRIES) {
      throw new AclException("Invalid ACL: ACL has " + defaultEntries.size() + " default entries, which exceeds maximum of " + MAX_ENTRIES + ".");
    }
  }

  private static void calculateMasks(List<AclEntry> aclBuilder, EnumMap<AclEntryScope, AclEntry> providedMask, EnumSet<AclEntryScope> maskDirty, EnumSet<AclEntryScope> scopeDirty) throws AclException {
    EnumSet<AclEntryScope> scopeFound = EnumSet.noneOf(AclEntryScope.class);
    EnumMap<AclEntryScope, FsAction> unionPerms = Maps.newEnumMap(AclEntryScope.class);
    EnumSet<AclEntryScope> maskNeeded = EnumSet.noneOf(AclEntryScope.class);
    // Determine which scopes are present, which scopes need a mask, and the
    // union of group class permissions in each scope.
    for (AclEntry entry : aclBuilder) {
      scopeFound.add(entry.getScope());
      if (entry.getType() == GROUP || entry.getName() != null) {
        FsAction scopeUnionPerms = unionPerms.get(entry.getScope());
        if (scopeUnionPerms == null) {
          scopeUnionPerms = FsAction.NONE;
        }
        unionPerms.put(entry.getScope(), scopeUnionPerms.or(entry.getPermission()));
      }

View on GitHub (pinned to c9a67b23e8)

Solutions

  1. Trim default entries so only necessary inheritance rules remain; default entries only need base trio plus genuinely inherited grants.
  2. Use replaceAclEntries with a compact spec instead of accumulating merges.
  3. Encode bulk inheritance via groups rather than per-user default entries.

Example fix

// before
mergeAclEntries(dir, "default:user:u1:rwx,default:user:u2:rwx,..."); // > MAX_ENTRIES default entries
// after
mergeAclEntries(dir, "default:user::rwx,default:group::r-x,default:group:team:rwx,default:other::r--");
Defensive patterns

Strategy: validation

Validate before calling

if (defaultEntries.size() > MAX_ENTRIES) {
  throw new IllegalArgumentException("too many default entries: " + defaultEntries.size());
}

Try / catch

try {
  mergeAclEntries(dir, spec);
} catch (AclException e) {
  if (e.getMessage().contains("default entries, which exceeds maximum")) {
    spec = pruneDefaultEntries(spec);
    replaceAclEntries(dir, spec);
  } else throw e;
}

Prevention

When it happens

Trigger: mergeAclEntries/replaceAclEntries producing a DEFAULT-scope ACL with more than MAX_ENTRIES entries, typically by repeatedly merging named default user/group entries into a directory's ACL.

Common situations: Setting inheritance rules for many named users on a directory; repeated merges of default entries across scripts until the cap is crossed.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/3a2cb7b0541b7723. Report an issue: GitHub.