apache/hadoop · error · IllegalArgumentException

A valid name must be specified.

Error message

A valid name must be specified.

What it means

Thrown by AzureBlobFileSystem.getXAttr when the requested attribute name is null or empty. The name is required to look up the corresponding path property on the service; the check fires before any request is sent. Unlike missing-attribute cases (which return null), an invalid name is a caller bug.

Source

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

  }

  /**
   * Get the value of an attribute for a non-root path.
   *
   * @param path The path on which to get the attribute
   * @param name The attribute to get
   * @return The bytes of the attribute's value (encoded in latin-1)
   *         or null if the attribute does not exist
   * @throws IOException If there was an issue getting the attribute from Azure
   * @throws IllegalArgumentException If name is null or empty
   */
  @Override
  public byte[] getXAttr(final Path path, final String name)
      throws IOException {
    LOG.debug("AzureBlobFileSystem.getXAttr path: {}", path);

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

    Path qualifiedPath = makeQualified(path);

    byte[] value = null;
    try {
      TracingContext tracingContext = new TracingContext(clientCorrelationId,
          fileSystemId, FSOperationType.GET_ATTR, true, tracingHeaderFormat,
          listener);
      Hashtable<String, String> properties = getAbfsStore()
          .getPathStatus(qualifiedPath, tracingContext);
      String xAttrName = ensureValidAttributeName(name);
      if (properties.containsKey(xAttrName)) {
        String xAttrValue = properties.get(xAttrName);
        value = getAbfsStore().encodeAttribute(xAttrValue);
      }
    } catch (AzureBlobFileSystemException ex) {
      checkException(path, ex);

View on GitHub (pinned to 2add963021)

Solutions

1. Validate the name is non-null and non-empty before calling getXAttr.
2. Trace where the empty name is produced (split/trim/concat logic) and fix the producer.
3. Use fs.getXAttrs(path) to list all attributes when the name is genuinely unknown.

Example fix

// before
byte[] v = fs.getXAttr(path, namePart);

// after
if (namePart == null || namePart.isEmpty()) {
  throw new IllegalArgumentException("xattr name required, got: " + namePart);
}
byte[] v = fs.getXAttr(path, namePart);

if (name == null || name.isEmpty()) {
  return null; // or throw your own descriptive error
}
return fs.getXAttr(path, name);

static boolean hasText(String s) {
  return s != null && !s.isEmpty();
}

try {
  value = fs.getXAttr(path, name);
} catch (IllegalArgumentException e) {
  // invalid name is a programming error; fix the producer of the name
}

When it happens

Trigger: Calling fs.getXAttr(path, null) or fs.getXAttr(path, "") — often from a name built by string concatenation or split that produced an empty result.

Common situations: Parsing xattr names from user input or config where a blank value slips through; looping over a names list that contains empty strings; porting code that assumed whitespace trimming.

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 and value 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/00b8b9dc2d2e2785. Report an issue: GitHub.