apache/hadoop · error · IllegalArgumentException

Parameter [{0}], cannot be NULL

Error message

Parameter [{0}], cannot be NULL

What it means

UserParam.validateLength (UserParam.java:51-62) throws this MessageFormat'd IllegalArgumentException when the username it must embed in the user.name parameter is null. Only the UserParam(UserGroupInformation) constructor at UserParam.java:76-78 can reach it: it calls ugi.getShortUserName(), and the String constructor maps null/empty to 'parameter absent' instead. It therefore signals a UserGroupInformation whose short user name is null — a broken authentication identity rather than a bad HTTP parameter.

Source

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

      Pattern.compile(DFS_WEBHDFS_USER_PATTERN_DEFAULT));

  @VisibleForTesting
  public static Domain getUserPatternDomain() {
    return domain;
  }

  @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));
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Check UserGroupInformation.getLoginUser().getShortUserName() before issuing WebHDFS calls and fail fast with a clear message if it is null.
2. Fix the principal: keytabs must use user/host@REALM with a non-empty user part; re-run kinit and verify with klist.
3. In tests, use UserGroupInformation.createUserForTesting("user", groups) or RemoteUserMock instead of half-built UGIs.

Example fix

// before
UserGroupInformation ugi = UserGroupInformation.getCurrentUser();
conn.setRequestProperty... new UserParam(ugi).toQueryString()
// after
UserGroupInformation ugi = UserGroupInformation.getCurrentUser();
String shortName = ugi.getShortUserName();
if (shortName == null || shortName.isEmpty()) {
  throw new IllegalStateException("Kerberos principal has no user part: " + ugi.getUserName());
}

static UserGroupInformation requireNamedUgi() {
  UserGroupInformation ugi = UserGroupInformation.getLoginUser();
  if (ugi.getShortUserName() == null) throw new IllegalStateException("UGI has null short username: " + ugi.getUserName());
  return ugi;
}

static boolean hasShortUserName(UserGroupInformation ugi) { return ugi != null && ugi.getShortUserName() != null; }

When it happens

Trigger: new UserParam(UserGroupInformation.getCurrentUser()) when the current UGI's short name is null — e.g. a Kerberos principal with no user component ('@REALM' or a malformed principal), a UGI assembled with null in tests, or a custom authentication filter that produced an empty principal.

Common situations: Keytab login with a service principal missing its primary part; SPNEGO handshakes where the negotiated principal fails to parse; unit tests constructing UserGroupInformation.createProxyUser or mock UGIs without a real name; upgrading JDK/Kerberos libs that alter principal parsing.

Related errors

• Failed to obtain user group information: {}
• Parameter [{0}], it's length must be at least 1
• Security enabled but user not authenticated by filter
• Usernames not matched: name={shortName} != expected={expecte
• {} parameter is not null.

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