{"record":{"id":"b7b405d199a4bcff","repo":"apache/druid","slug":"principal-not-defined-in-configuration","errorCode":null,"errorMessage":"Principal not defined in configuration","messagePattern":"Principal not defined in configuration","errorType":"exception","errorClass":"ServletException","httpStatus":null,"severity":"critical","filePath":"extensions-core/druid-kerberos/src/main/java/org/apache/druid/security/kerberos/DruidKerberosAuthenticationHandler.java","lineNumber":80,"sourceCode":"    serverSubject = null;\n    for (LoginContext loginContext : loginContexts) {\n      try {\n        loginContext.logout();\n      }\n      catch (LoginException ex) {\n        log.warn(ex, ex.getMessage());\n      }\n    }\n    loginContexts.clear();\n  }\n\n  @Override\n  public void init(Properties config) throws ServletException\n  {\n    try {\n      String principal = config.getProperty(PRINCIPAL);\n      if (principal == null || principal.trim().length() == 0) {\n        throw new ServletException(\"Principal not defined in configuration\");\n      }\n      keytab = config.getProperty(KEYTAB, keytab);\n      if (keytab == null || keytab.trim().length() == 0) {\n        throw new ServletException(\"Keytab not defined in configuration\");\n      }\n      if (!new File(keytab).exists()) {\n        throw new ServletException(\"Keytab does not exist: \" + keytab);\n      }\n\n      // use all SPNEGO principals in the keytab if a principal isn't\n      // specifically configured\n      final String[] spnegoPrincipals;\n      if (\"*\".equals(principal)) {\n        spnegoPrincipals = KerberosUtil.getPrincipalNames(keytab, Pattern.compile(\"HTTP/.*\"));\n        if (spnegoPrincipals.length == 0) {\n          throw new ServletException(\"Principals do not exist in the keytab\");\n        }\n      } else {","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/extensions-core/druid-kerberos/src/main/java/org/apache/druid/security/kerberos/DruidKerberosAuthenticationHandler.java#L62-L98","documentation":"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.","triggerScenarios":"Initializing the Kerberos authenticator (druid.auth.authenticator.<name>.type=kerberos) without setting druid.auth.authenticator.<name>.principal, or setting it to empty/whitespace only.","commonSituations":"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.","solutions":["Set druid.auth.authenticator.<name>.principal to the Kerberos service principal, e.g. HTTP/_HOST@REALM.","Ensure the corresponding keytab property is also set and the keytab file exists on the host.","Check for typos in the property key spelling and that your templating actually substitutes the value.","Restart the service after adding the property; verify init succeeds in logs."],"exampleFix":"// before\ndruid.auth.authenticator.kerberos.type=kerberos\n# principal missing\n\n// after\ndruid.auth.authenticator.kerberos.type=kerberos\ndruid.auth.authenticator.kerberos.principal=HTTP/_HOST@EXAMPLE.COM\ndruid.auth.authenticator.kerberos.keytab=/etc/security/keytabs/http.service.keytab","handlingStrategy":"validation","validationCode":"String principal = props.getProperty(\"druid.auth.authenticator.\" + name + \".principal\");\nif (principal == null || principal.trim().isEmpty()) {\n  throw new IllegalArgumentException(\"Kerberos principal must be set: druid.auth.authenticator.\" + name + \".principal\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  handler.init(config);\n} catch (ServletException e) {\n  if (e.getMessage().contains(\"Principal not defined\")) {\n    // fail deployment fast with a clear config message\n  }\n}","preventionTips":["Always set druid.auth.authenticator.<name>.principal when type=kerberos.","Validate the full Kerberos property set (principal, keytab, authToLocalPatterns) in deployment checks.","Watch for template substitution leaving empty values.","Avoid common typos like 'principle'."],"tags":["kerberos","authentication","configuration"],"backgroundTag":"missing-required-config-field","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}