apache/hadoop · error · IllegalArgumentException

The permission can't be null

Error message

The permission can't be null

What it means

Thrown by AzureBlobFileSystem.setPermission when the FsPermission argument is null on an HNS-enabled account. Permission bits are required to build the backend SetAccessControl request, so a null cannot be applied. Non-HNS accounts delegate to the superclass and never hit this check; note that in RBAC-only mode (fs.azure.rbac.only) a valid non-null permission is accepted but the backend call is skipped as a no-op.

Source

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

   * Set permission of a path.
   *
   * @param path       The path
   * @param permission Access permission
   */
  @Override
  public void setPermission(final Path path, final FsPermission permission)
      throws IOException {
    LOG.debug("AzureBlobFileSystem.setPermission path: {}", path);
    TracingContext tracingContext = new TracingContext(clientCorrelationId,
        fileSystemId, FSOperationType.SET_PERMISSION, true, tracingHeaderFormat, listener);

    if (!getIsNamespaceEnabled(tracingContext)) {
      super.setPermission(path, permission);
      return;
    }

    if (permission == null) {
      throw new IllegalArgumentException("The permission can't be null");
    }

    // RBAC-only short-circuit: when fs.azure.rbac.only=true on an HNS-enabled
    // account, skip the backend SetAccessControl call. Framework-generated
    // setPermission() invocations (Spark/Hadoop commit protocols, distcp, etc.)
    // succeed as no-ops so RBAC-only deployments are not blocked by lack of
    // ACL-management permissions. Explicit ACL APIs are unaffected.
    if (getAbfsStore().getAbfsConfiguration().isRbacOnlyMode()) {
      LOG.debug("RBAC-only mode enabled; skipping setPermission for path: {}", path);
      return;
    }

    Path qualifiedPath = makeQualified(path);

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

View on GitHub (pinned to 2add963021)

Solutions

1. Pass an explicit FsPermission, e.g. FsPermission.valueOf("644").
2. Derive a default from config (fs.permissions.umask-mode / FileSystem.getUMask) instead of forwarding null.
3. Skip the setPermission call when no permission is available.

Example fix

// before
fs.setPermission(path, requestedPermission); // may be null

// after
FsPermission perm = requestedPermission != null
    ? requestedPermission
    : FsPermission.getFileDefault();
fs.setPermission(path, perm);

FsPermission effective = permission != null ? permission : FsPermission.getFileDefault();
fs.setPermission(path, effective);

static boolean isSettable(FsPermission p) {
  return p != null;
}

try {
  fs.setPermission(path, permission);
} catch (IllegalArgumentException e) {
  // permission was null: apply a default and retry once, or fail fast
}

When it happens

Trigger: Calling fs.setPermission(path, null) on an account where getIsNamespaceEnabled() returns true.

Common situations: Frameworks deriving the permission from configuration that returned null; forwarding FileStatus.getPermission() from another filesystem instance that yielded null; optional permission parameters defaulting 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.
• A valid name and value must be specified.
• A valid name must be specified.
• The value of the aclSpec parameter is invalid.
• The aclSpec argument is invalid.

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