apache/hadoop · error · IOException

Usernames not matched: expecting null but name={name}

Error message

Usernames not matched: expecting null but name={name}

What it means

JspHelper.checkUsername(expected, name) throws IOException('Usernames not matched: expecting null but name=...') when expected == null but name != null. Its production caller is DataNodeUGIProvider (DataNodeUGIProvider.java:146), which passes the token-derived UGI short name as 'expected' and the user.name query parameter as 'name': a request that supplies user.name while the authenticated identity produced no username is rejected as a mismatch rather than trusted.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/JspHelper.java:211

      final String clientAddr = proxyHeader.split(",")[0].trim();
      if (!clientAddr.isEmpty()) {
        remoteAddr = clientAddr;
      }
    }
    return remoteAddr;
  }

  public static int getRemotePort(HttpServletRequest request) {
    return request.getRemotePort();
  }

  /**
   * Expected user name should be a short name.
   */
  public static void checkUsername(final String expected, final String name
      ) throws IOException {
    if (expected == null && name != null) {
      throw new IOException("Usernames not matched: expecting null but name="
          + name);
    }
    if (name == null) { //name is optional, null is okay
      return;
    }
    KerberosName u = new KerberosName(name);
    String shortName = u.getShortName();
    if (!shortName.equals(expected)) {
      throw new IOException("Usernames not matched: name=" + shortName
          + " != expected=" + expected);
    }
  }

  private static String getUsernameFromQuery(final HttpServletRequest request,
      final boolean tryUgiParameter) {
    String username = request.getParameter(UserParam.NAME);
    if (username == null && tryUgiParameter) {
      //try ugi parameter

View on GitHub (pinned to 2add963021)

Solutions

1. Drop the user.name parameter from the request — under security the token identity is authoritative
2. Obtain and pass a fresh, valid delegation token (WebHDFS GETDELEGATIONTOKEN) and verify its owner field is populated
3. If tokens systematically resolve to empty owners, review auth_to_local / hadoop.security.auth_to_local rules for the issuing principal

Example fix

# before (token with empty owner + explicit user)
curl 'http://dn:9864/webhdfs/v1/f?op=OPEN&delegation=<token>&user.name=alice'

# after (token identity only)
curl 'http://dn:9864/webhdfs/v1/f?op=OPEN&delegation=<token>'

UserGroupInformation tokenUgi = getUgiFromToken(tokenString); // DataNodeUGIProvider path
String fromQuery = request.getParameter(UserParam.NAME);
if (tokenUgi != null && tokenUgi.getShortUserName() == null && fromQuery != null) {
  resp.sendError(403, "user.name supplied but token identity has no username");
  return;
}
JspHelper.checkUsername(tokenUgi.getShortUserName(), fromQuery);

try {
  JspHelper.checkUsername(expected, name);
} catch (IOException e) {
  if (e.getMessage().startsWith("Usernames not matched: expecting null")) {
    resp.sendError(403, "user.name parameter conflicts with token identity");
  } else throw e;
}

When it happens

Trigger: Secured DataNode WebHDFS request where a delegation token's owner resolves to a null/empty short username while the request URL also carries a user.name parameter (the token path deliberately ignores user.name, so any residual name with a nameless identity trips this check).

Common situations: Malformed or truncated delegation token string in the URL; token minted for a principal whose auth_to_local mapping yields an empty name; client libraries that always append user.name to DataNode URLs.

Related errors

• Usernames not matched: name={shortName} != expected={expecte
• {} parameter is not null.
• Failed to find datanode, suggest to check cluster health. ex
• request UGI cannot be NULL
• Fetch of delegation token failed

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