apache/hadoop · error · IllegalArgumentException

The value of the aclSpec parameter is invalid.

Error message

The value of the aclSpec parameter is invalid.

What it means

Thrown by AzureBlobFileSystem.modifyAclEntries when the aclSpec list is null or empty, after the HNS check passes. Merging an empty set of entries is meaningless, so the driver rejects it before contacting the service. It signals a caller bug, not a service or permission problem.

Source

Thrown at hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/AzureBlobFileSystem.java:1265

   * @param aclSpec List of AbfsAclEntry describing modifications
   * @throws IOException if an ACL could not be modified
   */
  @Override
  public void modifyAclEntries(final Path path, final List<AclEntry> aclSpec)
      throws IOException {
    LOG.debug("AzureBlobFileSystem.modifyAclEntries path: {}", path);
    TracingContext tracingContext = new TracingContext(clientCorrelationId,
        fileSystemId, FSOperationType.MODIFY_ACL, true, tracingHeaderFormat,
        listener);

    if (!getIsNamespaceEnabled(tracingContext)) {
      throw new UnsupportedOperationException(
          "modifyAclEntries is only supported by storage accounts with the "
              + "hierarchical namespace enabled.");
    }

    if (aclSpec == null || aclSpec.isEmpty()) {
      throw new IllegalArgumentException("The value of the aclSpec parameter is invalid.");
    }

    Path qualifiedPath = makeQualified(path);

    try {
      getAbfsStore().modifyAclEntries(qualifiedPath, aclSpec, tracingContext);
    } catch (AzureBlobFileSystemException ex) {
      checkException(path, ex);
    }
  }

  /**
   * Removes ACL entries from files and directories.  Other ACL entries are
   * retained.
   *
   * @param path    Path to modify
   * @param aclSpec List of AclEntry describing entries to remove
   * @throws IOException if an ACL could not be modified

View on GitHub (pinned to 2add963021)

Solutions

1. Skip the call when the list is null or empty.
2. Inspect how the list was built (parse/filter steps) and fix the empty result.
3. Validate the spec string before parsing with AclEntry.parseAclSpec.

Example fix

// before
fs.modifyAclEntries(path, entries);

// after
if (entries != null && !entries.isEmpty()) {
  fs.modifyAclEntries(path, entries);
}

if (aclSpec == null || aclSpec.isEmpty()) {
  return; // nothing to modify
}
fs.modifyAclEntries(path, aclSpec);

static boolean isNonEmpty(List<AclEntry> l) {
  return l != null && !l.isEmpty();
}

try {
  fs.modifyAclEntries(path, aclSpec);
} catch (IllegalArgumentException e) {
  // empty/null spec: fix the entry producer, do not retry
}

When it happens

Trigger: Calling fs.modifyAclEntries(path, null) or fs.modifyAclEntries(path, Collections.emptyList()) on an HNS-enabled account.

Common situations: AclEntry.parseAclSpec output filtered down to nothing on malformed input; ACL-diff logic computing an empty change set and calling modify anyway; defaulting a missing config to null.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• A valid owner or group must be specified.
• The aclSpec argument is invalid.
• A valid name and value must be specified.
• A valid name must be specified.
• The permission can't be null

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