{"record":{"id":"63d81667b5931363","repo":"apache/hadoop","slug":"problem-with-kerberos-auth-to-local-name-configura","errorCode":null,"errorMessage":"Problem with Kerberos auth_to_local name configuration","messagePattern":"Problem with Kerberos auth_to_local name configuration","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/UserGroupInformation.java","lineNumber":316,"sourceCode":"        if (!isInitialized()) { // someone might have beat us\n          initialize(new Configuration(), false);\n        }\n      }\n    }\n  }\n\n  /**\n   * Initialize UGI and related classes.\n   * @param conf the configuration to use\n   */\n  private static synchronized void initialize(Configuration conf,\n                                              boolean overrideNameRules) {\n    authenticationMethod = SecurityUtil.getAuthenticationMethod(conf);\n    if (overrideNameRules || !HadoopKerberosName.hasRulesBeenSet()) {\n      try {\n        HadoopKerberosName.setConfiguration(conf);\n      } catch (IOException ioe) {\n        throw new RuntimeException(\n            \"Problem with Kerberos auth_to_local name configuration\", ioe);\n      }\n    }\n    try {\n        kerberosMinSecondsBeforeRelogin = 1000L * conf.getLong(\n                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN,\n                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN_DEFAULT);\n    }\n    catch(NumberFormatException nfe) {\n        throw new IllegalArgumentException(\"Invalid attribute value for \" +\n                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN + \" of \" +\n                conf.get(HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN));\n    }\n\n    kerberosKeyTabLoginRenewalEnabled = conf.getBoolean(\n            HADOOP_KERBEROS_KEYTAB_LOGIN_AUTORENEWAL_ENABLED,\n            HADOOP_KERBEROS_KEYTAB_LOGIN_AUTORENEWAL_ENABLED_DEFAULT);\n","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/UserGroupInformation.java#L298-L334","documentation":"UserGroupInformation.initialize applies hadoop.security.auth_to_local to HadoopKerberosName. HadoopKerberosName.setConfiguration throws IOException when a rule cannot be parsed (bad RULE syntax, invalid regex, malformed s/// substitution). UGI wraps it in a RuntimeException, so the first UGI use in the JVM usually aborts application startup.","triggerScenarios":"First call to UserGroupInformation.getLoginUser()/setConfiguration with a core-site.xml whose hadoop.security.auth_to_local contains an unparseable rule or an unterminated rule list.","commonSituations":"Hand-edited auth_to_local with regex typos; rules copied from MIT Kerberos docs into XML without escaping & or <; missing closing parenthesis in RULE:[...] or in the substitution; whitespace/property-formatting errors in the XML value.","solutions":["After loading the config, validate with `hadoop org.apache.hadoop.security.HadoopKerberosName <principal>` which surfaces the exact rule parse error","Escape XML specials inside rule regexes (&amp; &lt;) in core-site.xml","Reduce the rule set to a known-good single rule plus DEFAULT, then re-add rules one at a time until the offender is found","Always terminate the rule list with DEFAULT"],"exampleFix":"<!-- before -->\n<property>\n  <name>hadoop.security.auth_to_local</name>\n  <value>RULE:[1:$1@$0](.*@EXAMPLE.COM)s/@EXAMPLE.COM//</value>\n</property>\n<!-- after: escaped ampersand and trailing DEFAULT -->\n<property>\n  <name>hadoop.security.auth_to_local</name>\n  <value>RULE:[1:$1@$0](.*@EXAMPLE&amp;.COM)s/@EXAMPLE.COM//\n    DEFAULT</value>\n</property>","handlingStrategy":"validation","validationCode":"// Fail at config-load time with a clear message, not at first UGI use\nConfiguration conf = new Configuration();\ntry {\n  org.apache.hadoop.security.HadoopKerberosName.setConfiguration(conf);\n} catch (IOException e) {\n  throw new RuntimeException(\"auth_to_local rules are invalid - fix core-site.xml\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n  UserGroupInformation.setConfiguration(conf);\n} catch (RuntimeException e) {\n  if (e.getMessage().contains(\"auth_to_local\")) {\n    throw new ConfigurationException(\"bad hadoop.security.auth_to_local\", e);\n  }\n  throw e;\n}","preventionTips":["Lint auth_to_local in CI with HadoopKerberosName.setConfiguration before deployment","Escape XML specials in rule regexes","Keep a trailing DEFAULT rule in every environment's core-site.xml"],"tags":["hadoop","kerberos","auth-to-local","configuration","ugi"],"backgroundTag":"kerberos-auth-to-local-misconfigured","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}