apache/hadoop · error · ServletException

Principal not defined in configuration

Error message

Principal not defined in configuration

What it means

Error "Principal not defined in configuration" thrown in apache/hadoop.

Source

Thrown at hadoop-common-project/hadoop-auth/src/main/java/org/apache/hadoop/security/authentication/server/KerberosAuthenticationHandler.java:148

  /**
   * Initializes the authentication handler instance.
   * <p>
   * It creates a Kerberos context using the principal and keytab specified in
   * the configuration.
   * <p>
   * This method is invoked by the {@link AuthenticationFilter#init} method.
   *
   * @param config configuration properties to initialize the handler.
   *
   * @throws ServletException thrown if the handler could not be initialized.
   */
  @Override
  public void init(Properties config) throws ServletException {
    try {
      String principal = config.getProperty(PRINCIPAL);
      if (principal == null || principal.trim().length() == 0) {
        throw new ServletException("Principal not defined in configuration");
      }
      keytab = config.getProperty(KEYTAB, keytab);
      if (keytab == null || keytab.trim().length() == 0) {
        throw new ServletException("Keytab not defined in configuration");
      }
      File keytabFile = new File(keytab);
      if (!keytabFile.exists()) {
        throw new ServletException("Keytab does not exist: " + keytab);
      }
      
      // use all SPNEGO principals in the keytab if a principal isn't
      // specifically configured
      final String[] spnegoPrincipals;
      if (principal.equals("*")) {
        spnegoPrincipals = KerberosUtil.getPrincipalNames(
            keytab, Pattern.compile("HTTP/.*"));
        if (spnegoPrincipals.length == 0) {
          throw new ServletException("Principals do not exist in the keytab");

View on GitHub (pinned to 2add963021)

Solutions

1. Set the Kerberos principal in the handler configuration (kerberos.principal property).

Example fix

Add init-param kerberos.principal=HTTP/host@REALM.

When it happens

Trigger: Raised at runtime when the documented precondition or configuration requirement for this operation is violated.

Common situations: Misconfigured or missing property, invalid user input, or calling the API before its prerequisites are met.

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