apache/hadoop · error · UnsupportedOperationException

modifyAclEntries is only supported by storage accounts with

Error message

modifyAclEntries is only supported by storage accounts with the hierarchical namespace enabled.

What it means

Thrown by AzureBlobFileSystem.modifyAclEntries when the storage account does not have the hierarchical namespace (HNS) enabled. ACL modification is a POSIX-semantics feature only available on HNS accounts; flat-namespace blob accounts cannot honor it, so the driver refuses up front instead of failing at the service. The namespace state is resolved (and cached) by getIsNamespaceEnabled, which probes the service if unknown.

Source

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

   * Modifies ACL entries of files and directories.  This method can add new ACL
   * entries or modify the permissions on existing ACL entries.  All existing
   * ACL entries that are not specified in this call are retained without
   * changes.  (Modifications are merged into the current ACL.)
   *
   * @param path    Path to modify
   * @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);
    }
  }

  /**

View on GitHub (pinned to 2add963021)

Solutions

  1. Use a storage account with hierarchical namespace enabled (required for ACL APIs).
  2. Gate ACL propagation in the calling framework (disable ACL sync features on flat accounts).
  3. Feature-detect by catching UnsupportedOperationException and degrade gracefully.

Example fix

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

// after
try {
  fs.modifyAclEntries(path, entries);
} catch (UnsupportedOperationException e) {
  LOG.warn("ACL APIs unavailable; account lacks hierarchical namespace: {}", path);
}
Defensive patterns

Strategy: try-catch

Validate before calling

static boolean isAclCapable(FileSystem fs) {
  try {
    fs.getAclStatus(new Path("/"));
    return true;
  } catch (UnsupportedOperationException e) {
    return false;
  } catch (IOException e) {
    return true; // service reachable and HNS probe passed the client check
  }
}

Try / catch

try {
  fs.modifyAclEntries(path, entries);
} catch (UnsupportedOperationException e) {
  LOG.warn("ACL APIs need hierarchical namespace; skipping: {}", path);
}

Prevention

When it happens

Trigger: Calling fs.modifyAclEntries(path, entries) against an ABFS endpoint whose account was created without hierarchical namespace (flat namespace).

Common situations: Account provisioned without HNS; pointing jobs at a legacy blob account via abfs://; Hive/Spark/Ranger plugins that propagate ACLs unconditionally; test suites run against non-HNS emulators or accounts.

Related errors

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