apache/hadoop · error · KerberosAuthException

Provided Subject must contain a KerberosPrincipal

Error message

Provided Subject must contain a KerberosPrincipal

What it means

getUGIFromSubject requires at least one KerberosPrincipal in the Subject, else it throws KerberosAuthException(SUBJECT_MUST_CONTAIN_PRINCIPAL). This API is only for wrapping externally performed Kerberos logins; subjects carrying other principal types do not qualify.

Source

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

  /**
   * 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
   */
  @InterfaceAudience.Public
  @InterfaceStability.Evolving
  public static UserGroupInformation getLoginUser() throws IOException {
    ensureInitialized();

View on GitHub (pinned to 2add963021)

Solutions

1. Perform the external login with a client Krb5LoginModule so a KerberosPrincipal lands in the Subject
2. For standard flows use loginUserFromKeytab or loginUserFromTicketCache instead of building subjects
3. For non-Kerberos remote identities use UGI.createRemoteUser, not getUGIFromSubject

if (subject.getPrincipals(javax.security.auth.kerberos.KerberosPrincipal.class)
        .isEmpty()) {
  throw new IllegalArgumentException(
      "subject must contain a KerberosPrincipal before getUGIFromSubject");
}

static boolean hasKerberosPrincipal(Subject s) {
  return !s.getPrincipals(
      javax.security.auth.kerberos.KerberosPrincipal.class).isEmpty();
}

When it happens

Trigger: Calling getUGIFromSubject with a Subject whose principals include User/RealUser/GenericPrincipal but no javax.security.auth.kerberos.KerberosPrincipal - e.g., a simple-auth subject, a ticket-cache login that failed before adding its principal, or a subject from the wrong JAAS entry.

Common situations: SSO/web filters handing over subjects without Kerberos credentials; hand-built test subjects; LoginContext using a JAAS config entry (like the server-side one) that does not add a KerberosPrincipal.

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
• Subject does not contain a valid User

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