apache/hadoop · error · IllegalArgumentException

Storage policy name is empty.

Error message

Storage policy name is empty.

What it means

Thrown by the NameNode-side WebHDFS PUT handler (put() covers op=SETSTORAGEPOLICY) when the request carries no storagepolicy query parameter. The handler checks policyName.getValue() == null and rejects the call with IllegalArgumentException before the filesystem is touched; WebHDFS surfaces it to the REST client as an HTTP 400 RemoteException reading 'Storage policy name is empty.'.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/web/resources/NamenodeWebHdfsMethods.java:940

      String snapshotPath =
          cp.createSnapshot(fullpath, snapshotName.getValue());
      final String js = JsonUtil.toJsonString(
          org.apache.hadoop.fs.Path.class.getSimpleName(), snapshotPath);
      return Response.ok(js).type(MediaType.APPLICATION_JSON).build();
    }
    case RENAMESNAPSHOT: {
      validateOpParams(op, oldSnapshotName, snapshotName);
      cp.renameSnapshot(fullpath, oldSnapshotName.getValue(),
          snapshotName.getValue());
      return Response.ok().type(MediaType.APPLICATION_OCTET_STREAM).build();
    }
    case DISALLOWSNAPSHOT: {
      cp.disallowSnapshot(fullpath);
      return Response.ok().type(MediaType.APPLICATION_OCTET_STREAM).build();
    }
    case SETSTORAGEPOLICY: {
      if (policyName.getValue() == null) {
        throw new IllegalArgumentException("Storage policy name is empty.");
      }
      cp.setStoragePolicy(fullpath, policyName.getValue());
      return Response.ok().type(MediaType.APPLICATION_OCTET_STREAM).build();
    }
    case SATISFYSTORAGEPOLICY:
      cp.satisfyStoragePolicy(fullpath);
      return Response.ok().type(MediaType.APPLICATION_OCTET_STREAM).build();

    case ENABLEECPOLICY:
      validateOpParams(op, ecpolicy);
      cp.enableErasureCodingPolicy(ecpolicy.getValue());
      return Response.ok().type(MediaType.APPLICATION_OCTET_STREAM).build();
    case DISABLEECPOLICY:
      validateOpParams(op, ecpolicy);
      cp.disableErasureCodingPolicy(ecpolicy.getValue());
      return Response.ok().type(MediaType.APPLICATION_OCTET_STREAM).build();
    case SETECPOLICY:
      validateOpParams(op, ecpolicy);

View on GitHub (pinned to 2add963021)

Solutions

  1. Add the parameter to the request: ...&op=SETSTORAGEPOLICY&storagepolicy=WARM (valid built-ins: HOT, WARM, COLD, ALL_SSD, ONE_SSD, LAZY_PERSIST, or a user-defined policy name)
  2. List the cluster's policy names first with GET /webhdfs/v1/?op=GETSTORAGEPOLICIES and copy one exactly
  3. If the policy is custom, confirm it exists and is enabled via hdfs dfsadmin -listStoragePolicies / -addStoragePolicies
  4. Dump the request actually sent (curl -v) to check whether a proxy stripped the parameter

Example fix

# before
PUT /webhdfs/v1/data?op=SETSTORAGEPOLICY&user.name=hdfs
# 400 ... java.lang.IllegalArgumentException: Storage policy name is empty.

# after
PUT /webhdfs/v1/data?op=SETSTORAGEPOLICY&storagepolicy=ALL_SSD&user.name=hdfs
Defensive patterns

Strategy: validation

Validate before calling

static String setStoragePolicyUrl(String path, String policy) {
  if (policy == null || policy.isEmpty()) {
    throw new IllegalArgumentException("storagepolicy query parameter is required for op=SETSTORAGEPOLICY");
  }
  return "/webhdfs/v1" + path + "?op=SETSTORAGEPOLICY&storagepolicy="
      + URLEncoder.encode(policy, StandardCharsets.UTF_8);
}

Try / catch

try {
  httpPut(setStoragePolicyUrl(path, policy));
} catch (IOException e) { // HTTP 400 -> RemoteException: java.lang.IllegalArgumentException
  if (e.getMessage() != null && e.getMessage().contains("Storage policy name is empty")) {
    throw new IllegalStateException("storagepolicy parameter missing from request URL", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: PUT /webhdfs/v1/<path>?op=SETSTORAGEPOLICY without a storagepolicy=<name> parameter. Typical with hand-written curl scripts, gateway/filter layers (HttpFS proxies, Knox) that drop unknown query parameters, and custom clients ported from DistributedFileSystem.setStoragePolicy() that forget the REST-side parameter.

Common situations: Scripts that copy one op= URL template for every operation; API wrappers that build query strings from a generic map which omits null values; version drift where a client library stopped appending the parameter; automation applying policies right after path creation.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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