{"record":{"id":"a3b42f0a71bcaa1b","repo":"apache/hadoop","slug":"provided-subject-must-contain-a-kerberosprincipal","errorCode":null,"errorMessage":"Provided Subject must contain a KerberosPrincipal","messagePattern":"Provided Subject must contain a KerberosPrincipal","errorType":"exception","errorClass":"KerberosAuthException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/UserGroupInformation.java","lineNumber":657,"sourceCode":"  /**\n   * Create a UserGroupInformation from a Subject with Kerberos principal.\n   *\n   * @param subject             The KerberosPrincipal to use in UGI.\n   *                            The creator of subject is responsible for\n   *                            renewing credentials.\n   *\n   * @throws IOException raised on errors performing I/O.\n   * @throws KerberosAuthException if the kerberos login fails\n   * @return UserGroupInformation\n   */\n  public static UserGroupInformation getUGIFromSubject(Subject subject)\n      throws IOException {\n    if (subject == null) {\n      throw new KerberosAuthException(SUBJECT_MUST_NOT_BE_NULL);\n    }\n\n    if (subject.getPrincipals(KerberosPrincipal.class).isEmpty()) {\n      throw new KerberosAuthException(SUBJECT_MUST_CONTAIN_PRINCIPAL);\n    }\n\n    // null params indicate external subject login.  no login context will\n    // be attached.\n    return doSubjectLogin(subject, null);\n  }\n\n  /**\n   * Get the currently logged in user.  If no explicit login has occurred,\n   * the user will automatically be logged in with either kerberos credentials\n   * if available, or as the local OS user, based on security settings.\n   * @return the logged in user\n   * @throws IOException if login fails\n   */\n  @InterfaceAudience.Public\n  @InterfaceStability.Evolving\n  public static UserGroupInformation getLoginUser() throws IOException {\n    ensureInitialized();","sourceCodeStart":639,"sourceCodeEnd":675,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/UserGroupInformation.java#L639-L675","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Perform the external login with a client Krb5LoginModule so a KerberosPrincipal lands in the Subject","For standard flows use loginUserFromKeytab or loginUserFromTicketCache instead of building subjects","For non-Kerberos remote identities use UGI.createRemoteUser, not getUGIFromSubject"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (subject.getPrincipals(javax.security.auth.kerberos.KerberosPrincipal.class)\n        .isEmpty()) {\n  throw new IllegalArgumentException(\n      \"subject must contain a KerberosPrincipal before getUGIFromSubject\");\n}","typeGuard":"static boolean hasKerberosPrincipal(Subject s) {\n  return !s.getPrincipals(\n      javax.security.auth.kerberos.KerberosPrincipal.class).isEmpty();\n}","tryCatchPattern":null,"preventionTips":["Perform external logins with a client Krb5LoginModule so the principal lands in the subject","Use loginUserFromKeytab/loginUserFromTicketCache for standard flows","Reserve getUGIFromSubject strictly for Kerberos-authenticated subjects"],"tags":["hadoop","kerberos","ugi","jaas-subject"],"backgroundTag":"missing-kerberos-principal","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}