apache/druid · critical · ServletException

Keytab not defined in configuration

Error message

Keytab not defined in configuration

What it means

During init of the Kerberos authentication handler, the configured keytab path (druid.auth.kerberos.serverKeytab or the KEYTAB config property) is missing or blank, so SPNEGO login cannot be performed. The handler throws a ServletException to abort startup because Kerberos server authentication is impossible without a keytab.

Source

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

      }
      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 {
        spnegoPrincipals = new String[]{principal};
      }

      String nameRules = config.getProperty(NAME_RULES, null);

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set druid.auth.kerberos.serverKeytab to the absolute path of a valid keytab file in the config Properties before init
2. Verify the config source actually loads the kerberos properties (correct runtime.properties / startup command)
3. If the keytab path is provisioned externally, confirm the provisioning step ran before service start

Example fix

// before
config = new Properties(); // missing KEYTAB
handler.init(config);
// after
config.setProperty("druid.auth.kerberos.serverKeytab", "/etc/security/keytabs/http.service.keytab");
handler.init(config);

String keytab = props.getProperty("druid.auth.kerberos.serverKeytab");
if (keytab == null || keytab.trim().isEmpty()) {
  throw new IllegalStateException("druid.auth.kerberos.serverKeytab must be set before handler init");
}

try { handler.init(config); } catch (ServletException e) { if (e.getMessage().contains("Keytab not defined")) { log.error("Missing keytab config"); } throw e; }

When it happens

Trigger: Calling DruidKerberosAuthenticationHandler.init(Properties) where config.getProperty(KEYTAB) returns null or a whitespace-only string and no default keytab field was set.

Common situations: Kerberos extension enabled but druid.auth.kerberos.serverKeytab not set in runtime.properties; property typo (serverKeytab vs keytab); config loader stripped the value; deploying with copied config missing the kerberos block.

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
• Set only one of 'key' or 'sharedAccessStorageToken' or 'useA
• SQLCatalogManager only works with SQL based metadata store a
• Principal not defined in configuration
• Principal not defined in configuration

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