apache/hadoop · error · IllegalArgumentException

Parameter [{0}], it's length must be at least 1

Error message

Parameter [{0}], it's length must be at least 1

What it means

The second guard in UserParam.validateLength (UserParam.java:56-60): a non-null username whose length is less than 1 — i.e. the empty string — throws this IllegalArgumentException. As with the null case, only the UserParam(UserGroupInformation) path can produce it, because the String constructor maps "" to absent; the message uses MessageFormat with the parameter name 'user.name'. It means the effective short username from the UGI is empty.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/UserParam.java:58

  }

  @VisibleForTesting
  public static void setUserPatternDomain(Domain dm) {
    domain = dm;
  }

  public static void setUserPattern(String pattern) {
    domain = new Domain(NAME, Pattern.compile(pattern));
  }

  private static String validateLength(String str) {
    if (str == null) {
      throw new IllegalArgumentException(
        MessageFormat.format("Parameter [{0}], cannot be NULL", NAME));
    }
    int len = str.length();
    if (len < 1) {
      throw new IllegalArgumentException(MessageFormat.format(
        "Parameter [{0}], it's length must be at least 1", NAME));
    }
    return str;
  }

  /**
   * Constructor.
   * @param str a string representation of the parameter value.
   */
  public UserParam(final String str) {
    super(domain, str == null ||
        str.equals(DEFAULT) ? null : validateLength(str));
  }

  /**
   * Construct an object from a UGI.
   */
  public UserParam(final UserGroupInformation ugi) {

View on GitHub (pinned to 2add963021)

Solutions

1. Validate the short username at startup: if ugi.getShortUserName() is empty, abort with a configuration error instead of calling WebHDFS.
2. Fix the principal/keytab so it has a real primary component (user@REALM); verify with klist and UserGroupInformation.getLoginUser().getUserName().
3. For proxied requests, ensure the effective user is never the empty string before building parameters.

Example fix

// before
params.add(new UserParam(UserGroupInformation.getCurrentUser()));
// after
String name = UserGroupInformation.getCurrentUser().getShortUserName();
Preconditions.checkState(name != null && !name.isEmpty(), "empty short username from UGI");
params.add(new UserParam(name));

static String requireNonEmptyShortName(UserGroupInformation ugi) {
  String n = ugi.getShortUserName();
  if (n == null || n.isEmpty()) throw new IllegalStateException("empty short username from UGI " + ugi.getUserName());
  return n;
}

static boolean hasNonEmptyShortUserName(UserGroupInformation ugi) {
  String n = ugi == null ? null : ugi.getShortUserName();
  return n != null && !n.isEmpty();
}

When it happens

Trigger: ugi.getShortUserName() returning "" — a principal like '/host@REALM' or '@REALM' whose primary component is empty; a proxy-user chain resolving to an empty name; test fixtures with UserGroupInformation.createRemoteUser("").

Common situations: Host-keytab principals without a primary; SPNEGO configurations that strip the realm and user part; custom auth filters deriving doAs users from headers that arrive empty; CI environments without a login user where the short name degenerates to empty.

Related errors

• Parameter [{0}], cannot be NULL
• {} parameter is not null.
• Failed to obtain user group information: {}
• Failed to parse "{str}" for the parameter {varName}. The va
• url must be for a HTTP or HTTPS resource

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