apache/hadoop · error · KerberosAuthException

Subject must not be null

Error message

Subject must not be null

What it means

UserGroupInformation.getUGIFromSubject rejects a null Subject immediately with KerberosAuthException(SUBJECT_MUST_NOT_BE_NULL) (an IOException subclass). The API exists to wrap an externally performed Kerberos login, so a null argument is a caller bug.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/UserGroupInformation.java:653

    params.put(LoginParam.CCACHE, ticketCache);
    return doSubjectLogin(null, params);
  }

  /**
   * Create a UserGroupInformation from a Subject with Kerberos principal.
   *
   * @param subject             The KerberosPrincipal to use in UGI.
   *                            The creator of subject is responsible for
   *                            renewing credentials.
   *
   * @throws IOException raised on errors performing I/O.
   * @throws KerberosAuthException if the kerberos login fails
   * @return UserGroupInformation
   */
  public static UserGroupInformation getUGIFromSubject(Subject subject)
      throws IOException {
    if (subject == null) {
      throw new KerberosAuthException(SUBJECT_MUST_NOT_BE_NULL);
    }

    if (subject.getPrincipals(KerberosPrincipal.class).isEmpty()) {
      throw new KerberosAuthException(SUBJECT_MUST_CONTAIN_PRINCIPAL);
    }

    // null params indicate external subject login.  no login context will
    // be attached.
    return doSubjectLogin(subject, null);
  }

  /**
   * Get the currently logged in user.  If no explicit login has occurred,
   * the user will automatically be logged in with either kerberos credentials
   * if available, or as the local OS user, based on security settings.
   * @return the logged in user
   * @throws IOException if login fails
   */

View on GitHub (pinned to 2add963021)

Solutions

1. Null-check the Subject before calling getUGIFromSubject
2. If the Subject came from Subject.getSubject(acc), run the code inside Subject.doAs so a subject is associated
3. When no explicit subject exists, fall back to UserGroupInformation.getLoginUser()

Example fix

// before
UserGroupInformation ugi = UserGroupInformation.getUGIFromSubject(subject);
// after
UserGroupInformation ugi = (subject != null)
    ? UserGroupInformation.getUGIFromSubject(subject)
    : UserGroupInformation.getLoginUser();

if (subject == null) {
  throw new IllegalArgumentException("subject required for getUGIFromSubject");
}

Objects.requireNonNull(subject, "kerberos subject must not be null");

When it happens

Trigger: getUGIFromSubject(null) - typically a variable never initialized, or an upstream login step returned null (e.g., Subject.getSubject(accessControlContext) outside a doAs scope).

Common situations: Optional LoginContext results not checked; calling Subject.getSubject(...) from a thread not running inside Subject.doAs; race where the subject field is read before assignment.

Related errors

• Illegal principal name " + name + ": " + ioe.toString()
• Failed to find user in name " + subject
• Problem with Kerberos auth_to_local name configuration
• Invalid attribute value for hadoop.kerberos.min.seconds.befo
• Provided Subject must contain a KerberosPrincipal

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