What causes "request UGI cannot be NULL" in apache/hadoop?

Authenticate the request: use Kerberos/SPNEGO, or with simple auth supply ?user.name= and set hadoop.http.authentication.simple.anonymous.allowed=false.

apache/hadoop · error · IllegalStateException

request UGI cannot be NULL

Error message

request UGI cannot be NULL

What it means

Server side of the HTTP delegation-token API. After the authentication handler runs, managementOperation expects the request UGI (the authenticated end-user identity) to be attached to the request. For GETDELEGATIONTOKEN it must be non-null because a token can only be minted for a real authenticated user; null triggers IllegalStateException "request UGI cannot be NULL", which HttpExceptionUtils converts into an HTTP 500.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/token/delegation/web/DelegationTokenAuthenticationHandler.java:270

              : null;
          // Create the proxy user if doAsUser exists
          String doAsUser = DelegationTokenAuthenticationFilter.getDoAs(request);
          if (requestUgi != null && doAsUser != null) {
            requestUgi = UserGroupInformation.createProxyUser(
                doAsUser, requestUgi);
            try {
              ProxyUsers.authorize(requestUgi, request.getRemoteAddr());
            } catch (AuthorizationException ex) {
              HttpExceptionUtils.createServletExceptionResponse(response,
                  HttpServletResponse.SC_FORBIDDEN, ex);
              return false;
            }
          }
          Map map = null;
          switch (dtOp) {
            case GETDELEGATIONTOKEN:
              if (requestUgi == null) {
                throw new IllegalStateException("request UGI cannot be NULL");
              }
              String renewer = ServletUtils.getParameter(request,
                  KerberosDelegationTokenAuthenticator.RENEWER_PARAM);
              String service = ServletUtils.getParameter(request,
                  KerberosDelegationTokenAuthenticator.SERVICE_PARAM);
              try {
                Token<?> dToken = tokenManager.createToken(requestUgi, renewer,
                    service);
                map = delegationTokenToJSON(dToken);
              } catch (IOException ex) {
                throw new AuthenticationException(ex.toString(), ex);
              }
              break;
            case RENEWDELEGATIONTOKEN:
              if (requestUgi == null) {
                throw new IllegalStateException("request UGI cannot be NULL");
              }
              String tokenToRenew = ServletUtils.getParameter(request,

View on GitHub (pinned to 2add963021)

Solutions

Authenticate the request: use Kerberos/SPNEGO, or with simple auth supply ?user.name=<user> and set hadoop.http.authentication.simple.anonymous.allowed=false.
If you run a custom handler, set the request UGI attribute in authenticate() (mirror PseudoDelegationTokenAuthenticationHandler) before returning the AuthenticationToken.
As the client, retry only after establishing real credentials - retrying anonymous always reproduces the 500.

Example fix

// before (server, custom handler)
public AuthenticationToken authenticate(HttpServletRequest req, HttpServletResponse rsp) { return token; }
// after: attach the UGI the DT handler expects
public AuthenticationToken authenticate(HttpServletRequest req, HttpServletResponse rsp) {
  AuthenticationToken token = ...;
  UserGroupInformation ugi = UserGroupInformation.createRemoteUser(token.getUserName());
  req.setAttribute(DelegationTokenAuthenticatedURL.DELEGATION_TOKEN_UGI_ATTRIBUTE, ugi);
  return token;
}

Defensive patterns

Strategy: validation

Validate before calling

// Server-side (filter init): anonymous access + token ops is a misconfiguration
if ("simple".equals(conf.get("hadoop.http.authentication.type"))
    && conf.getBoolean("hadoop.http.authentication.simple.anonymous.allowed", true)) {
  LOG.warn("anonymous requests reaching token ops will 500; disable anonymous access");
}
// Client-side: establish identity before requesting a token
UserGroupInformation ugi = UserGroupInformation.getLoginUser();
Preconditions.checkState(ugi.getRealUser() != null || !ugi.isAnonymous(),
    "authenticate (Kerberos or user.name) before GETDELEGATIONTOKEN");

Prevention

Set hadoop.http.authentication.simple.anonymous.allowed=false when token operations are exposed.
Always negotiate Kerberos (or pass user.name under simple auth) before GETDELEGATIONTOKEN.
Custom auth handlers must set the DELEGATION_TOKEN_UGI request attribute like the built-in handlers do.

When it happens

Trigger: A GETDELEGATIONTOKEN request arrives with requestUgi == null: anonymous access was permitted (simple auth with anonymous allowed) and no user was established, or a custom AuthenticationHandler/DelegationTokenAuthenticationHandler subclass failed to set the DELEGATION_TOKEN_UGI request attribute in its authenticate() before delegating.

Common situations: curl-ing the token endpoint without a user.name parameter while hadoop.http.authentication.simple.anonymous.allowed=true; custom auth handler integrations (header-based SSO frontends) that skip setting the UGI attribute; spnego fallback to anonymous.

Related errors

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