apache/druid · critical · ServletException

Principal not defined in configuration

Error message

Principal not defined in configuration

What it means

KerberosAuthenticator.initializeKerberosLogin validates that a server principal is configured before performing a JAAS login. A null/blank serverPrincipal (druid.auth.kerberos.serverPrincipal) makes SPNEGO login impossible, so it throws ServletException during filter init via doFilter.

Source

Thrown at extensions-core/druid-kerberos/src/main/java/org/apache/druid/security/kerberos/KerberosAuthenticator.java:501

      }

      return new AppConfigurationEntry[]{
          new AppConfigurationEntry(
              KerberosUtil.getKrb5LoginModuleName(),
              AppConfigurationEntry.LoginModuleControlFlag.REQUIRED,
              options
          )
      };
    }
  }

  private void initializeKerberosLogin() throws ServletException
  {
    String keytab;

    try {
      if (serverPrincipal == null || serverPrincipal.trim().length() == 0) {
        throw new ServletException("Principal not defined in configuration");
      }
      keytab = serverKeytab;
      if (keytab == null || keytab.trim().length() == 0) {
        throw new ServletException("Keytab not defined in configuration");
      }
      if (!new File(keytab).exists()) {
        throw new ServletException("Keytab does not exist: " + keytab);
      }

      Set<Principal> principals = new HashSet<>();
      principals.add(new KerberosPrincipal(serverPrincipal));
      Subject subject = new Subject(false, principals, new HashSet<>(), new HashSet<>());

      DruidKerberosConfiguration kerberosConfiguration = new DruidKerberosConfiguration(keytab, serverPrincipal);

      log.info("Login using keytab " + keytab + ", for principal " + serverPrincipal);
      loginContext = new LoginContext("", subject, null, kerberosConfiguration);
      loginContext.login();

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set druid.auth.kerberos.serverPrincipal (e.g. HTTP/_HOST@REALM) in the authenticator config
2. Confirm the authenticator JSON spec includes the kerberos properties block
3. Restart the service so the filter re-initializes with the corrected config

Example fix

// before
"druid.auth.authenticators": ["kerberos"] // no principal configured
// after
props.setProperty("druid.auth.kerberos.serverPrincipal", "HTTP/_HOST@EXAMPLE.COM");

String principal = props.getProperty("druid.auth.kerberos.serverPrincipal");
if (principal == null || principal.trim().isEmpty()) {
  throw new IllegalStateException("druid.auth.kerberos.serverPrincipal must be set");
}

try {
  authenticator.init(config);
} catch (ServletException e) {
  if (e.getMessage().contains("Principal not defined")) { log.error("serverPrincipal missing in kerberos config"); }
  throw e;
}

When it happens

Trigger: doFilter -> initializeKerberosLogin with serverPrincipal == null or whitespace, i.e. druid.auth.kerberos.serverPrincipal absent from the authenticator config.

Common situations: Kerberos authenticator added to the auth chain but its principal property omitted; typo in property name; config JSON for the authenticator missing the field.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Principal not defined in configuration
• Keytab not defined in configuration
• Principals do not exist in the keytab
• Keytab not defined in configuration
• Failed to login as [%s]

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/99261c5192d9cad0. Report an issue: GitHub.