apache/druid · critical · ServletException

Principal not defined in configuration

Error message

Principal not defined in configuration

What it means

DruidKerberosAuthenticationHandler.init() reads the Kerberos config Properties; the PRINCIPAL property is required. If it's absent or blank, init throws a ServletException, aborting the authentication handler initialization. The handler cannot authenticate requests without a service principal.

Source

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

    serverSubject = null;
    for (LoginContext loginContext : loginContexts) {
      try {
        loginContext.logout();
      }
      catch (LoginException ex) {
        log.warn(ex, ex.getMessage());
      }
    }
    loginContexts.clear();
  }

  @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");
      }
      if (!new File(keytab).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 ("*".equals(principal)) {
        spnegoPrincipals = KerberosUtil.getPrincipalNames(keytab, Pattern.compile("HTTP/.*"));
        if (spnegoPrincipals.length == 0) {
          throw new ServletException("Principals do not exist in the keytab");
        }
      } else {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set druid.auth.authenticator.<name>.principal to the Kerberos service principal, e.g. HTTP/_HOST@REALM.
2. Ensure the corresponding keytab property is also set and the keytab file exists on the host.
3. Check for typos in the property key spelling and that your templating actually substitutes the value.
4. Restart the service after adding the property; verify init succeeds in logs.

Example fix

// before
druid.auth.authenticator.kerberos.type=kerberos
# principal missing

// after
druid.auth.authenticator.kerberos.type=kerberos
druid.auth.authenticator.kerberos.principal=HTTP/_HOST@EXAMPLE.COM
druid.auth.authenticator.kerberos.keytab=/etc/security/keytabs/http.service.keytab

String principal = props.getProperty("druid.auth.authenticator." + name + ".principal");
if (principal == null || principal.trim().isEmpty()) {
  throw new IllegalArgumentException("Kerberos principal must be set: druid.auth.authenticator." + name + ".principal");
}

try {
  handler.init(config);
} catch (ServletException e) {
  if (e.getMessage().contains("Principal not defined")) {
    // fail deployment fast with a clear config message
  }
}

When it happens

Trigger: Initializing the Kerberos authenticator (druid.auth.authenticator.<name>.type=kerberos) without setting druid.auth.authenticator.<name>.principal, or setting it to empty/whitespace only.

Common situations: Kerberos enabled via auth config but the principal property left out of runtime.properties; property typo'd (e.g. 'principle'); config generated by templating that dropped the key; whitespace-only value from an unset env substitution.

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

• The gRPC query server requires either a Basic or Anonymous a
• Keytab not defined in configuration
• Failed to authenticate user principal [%s] with keytab [%s]
• Invalid AuthenticationToken type
• Principal not defined in configuration

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