apache/hadoop · critical · RuntimeException

Problem with Kerberos auth_to_local name configuration

Error message

Problem with Kerberos auth_to_local name configuration

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/UserGroupInformation.java:316

        if (!isInitialized()) { // someone might have beat us
          initialize(new Configuration(), false);
        }
      }
    }
  }

  /**
   * Initialize UGI and related classes.
   * @param conf the configuration to use
   */
  private static synchronized void initialize(Configuration conf,
                                              boolean overrideNameRules) {
    authenticationMethod = SecurityUtil.getAuthenticationMethod(conf);
    if (overrideNameRules || !HadoopKerberosName.hasRulesBeenSet()) {
      try {
        HadoopKerberosName.setConfiguration(conf);
      } catch (IOException ioe) {
        throw new RuntimeException(
            "Problem with Kerberos auth_to_local name configuration", ioe);
      }
    }
    try {
        kerberosMinSecondsBeforeRelogin = 1000L * conf.getLong(
                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN,
                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN_DEFAULT);
    }
    catch(NumberFormatException nfe) {
        throw new IllegalArgumentException("Invalid attribute value for " +
                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN + " of " +
                conf.get(HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN));
    }

    kerberosKeyTabLoginRenewalEnabled = conf.getBoolean(
            HADOOP_KERBEROS_KEYTAB_LOGIN_AUTORENEWAL_ENABLED,
            HADOOP_KERBEROS_KEYTAB_LOGIN_AUTORENEWAL_ENABLED_DEFAULT);

View on GitHub (pinned to 2add963021)

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 (& <) 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

Example fix

<!-- before -->
<property>
  <name>hadoop.security.auth_to_local</name>
  <value>RULE:[1:$1@$0](.*@EXAMPLE.COM)s/@EXAMPLE.COM//</value>
</property>
<!-- after: escaped ampersand and trailing DEFAULT -->
<property>
  <name>hadoop.security.auth_to_local</name>
  <value>RULE:[1:$1@$0](.*@EXAMPLE&amp;.COM)s/@EXAMPLE.COM//
    DEFAULT</value>
</property>

Defensive patterns

Strategy: validation

Validate before calling

// Fail at config-load time with a clear message, not at first UGI use
Configuration conf = new Configuration();
try {
  org.apache.hadoop.security.HadoopKerberosName.setConfiguration(conf);
} catch (IOException e) {
  throw new RuntimeException("auth_to_local rules are invalid - fix core-site.xml", e);
}

Try / catch

try {
  UserGroupInformation.setConfiguration(conf);
} catch (RuntimeException e) {
  if (e.getMessage().contains("auth_to_local")) {
    throw new ConfigurationException("bad hadoop.security.auth_to_local", e);
  }
  throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/63d81667b5931363. Report an issue: GitHub.