apache/hadoop · error · IllegalArgumentException

A valid name and value must be specified.

Error message

A valid name and value must be specified.

What it means

Thrown by AzureBlobFileSystem.setXAttr when the attribute name is null/empty or the value byte array is null. ABFS stores xattrs as path properties on the service, and a null value cannot be represented — removal is a separate removeXAttr operation. The check runs before any service call, so no network round trip is made.

Source

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

   * Set the value of an attribute for a non-root path.
   *
   * @param path The path on which to set the attribute
   * @param name The attribute to set
   * @param value The byte value of the attribute to set (encoded in latin-1)
   * @param flag The mode in which to set the attribute
   * @throws IOException If there was an issue setting the attribute on Azure
   * @throws IllegalArgumentException If name is null or empty or if value is null
   */
  @Override
  public void setXAttr(final Path path,
      final String name,
      final byte[] value,
      final EnumSet<XAttrSetFlag> flag)
      throws IOException {
    LOG.debug("AzureBlobFileSystem.setXAttr path: {}", path);

    if (name == null || name.isEmpty() || value == null) {
      throw new IllegalArgumentException("A valid name and value must be specified.");
    }

    Path qualifiedPath = makeQualified(path);

    try {
      TracingContext tracingContext = new TracingContext(clientCorrelationId,
          fileSystemId, FSOperationType.SET_ATTR, true, tracingHeaderFormat,
          listener);
      Hashtable<String, String> properties = getAbfsStore()
          .getPathStatus(qualifiedPath, tracingContext);
      String xAttrName = ensureValidAttributeName(name);
      boolean xAttrExists = properties.containsKey(xAttrName);
      XAttrSetFlag.validate(name, xAttrExists, flag);

      String xAttrValue = getAbfsStore().decodeAttribute(value);
      properties.put(xAttrName, xAttrValue);
      getAbfsStore().setPathProperties(qualifiedPath, properties, tracingContext);
    } catch (AzureBlobFileSystemException ex) {

View on GitHub (pinned to 2add963021)

Solutions

1. Pass an empty byte[0] instead of null when you mean 'no value'.
2. Use fs.removeXAttr(path, name) to delete an attribute.
3. Validate name is non-empty and value is non-null before the call.

Example fix

// before
fs.setXAttr(path, "user.tag", null, EnumSet.of(XAttrSetFlag.CREATE));

// after
fs.setXAttr(path, "user.tag", new byte[0], EnumSet.of(XAttrSetFlag.CREATE));

if (name == null || name.isEmpty() || value == null) {
  throw new IllegalArgumentException("setXAttr requires non-empty name and non-null value");
}
fs.setXAttr(path, name, value, flags);

static boolean isValidXAttrCall(String name, byte[] value) {
  return (name != null && !name.isEmpty()) && value != null;
}

try {
  fs.setXAttr(path, name, value, flags);
} catch (IllegalArgumentException e) {
  // argument bug: normalize and retry once with new byte[0], or rethrow
}

When it happens

Trigger: Calling fs.setXAttr(path, null, value, flags), fs.setXAttr(path, "", value, flags), or fs.setXAttr(path, name, null, flags).

Common situations: Code ported from HDFS, which permits a null xattr value (treated as empty) with the CREATE flag; dynamically built attribute names that concatenate to an empty string; intending to delete an attribute via setXAttr instead of removeXAttr.

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 name must be specified.
• A valid owner or group must be specified.
• The permission can't be null
• 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/a9650bf7c5fdaa0f. Report an issue: GitHub.