apache/hadoop · critical · IllegalArgumentException

Can't get Kerberos realm

Error message

Can't get Kerberos realm

What it means

When Hadoop security is set to kerberos (hadoop.security.authentication=kerberos or kerberos_ssl), HadoopKerberosName.setConfiguration calls KerberosUtil.getDefaultRealm() to validate that a Kerberos environment is usable before installing auth_to_local rules. Any failure from the JDK/Kerberos stack (missing krb5.conf, no default_realm, KDC unreachable in some implementations) is wrapped in IllegalArgumentException('Can't get Kerberos realm'). This surfaces during UserGroupInformation initialization, i.e. at JVM security bootstrap, not at first login.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/HadoopKerberosName.java:71

  /**
   * Set the static configuration to get and evaluate the rules.
   * <p>
   * IMPORTANT: This method does a NOP if the rules have been set already.
   * If there is a need to reset the rules, the {@link KerberosName#setRules(String)}
   * method should be invoked directly.
   * 
   * @param conf the new configuration
   * @throws IOException raised on errors performing I/O.
   */
  public static void setConfiguration(Configuration conf) throws IOException {
    final String defaultRule;
    switch (SecurityUtil.getAuthenticationMethod(conf)) {
      case KERBEROS:
      case KERBEROS_SSL:
        try {
          KerberosUtil.getDefaultRealm();
        } catch (Exception ke) {
          throw new IllegalArgumentException("Can't get Kerberos realm", ke);
        }
        defaultRule = "DEFAULT";
        break;
      default:
        // just extract the simple user name
        defaultRule = "RULE:[1:$1] RULE:[2:$1]";
        break; 
    }
    String ruleString = conf.get(HADOOP_SECURITY_AUTH_TO_LOCAL, defaultRule);
    setRules(ruleString);

    String ruleMechanism = conf.get(HADOOP_SECURITY_AUTH_TO_LOCAL_MECHANISM,  DEFAULT_MECHANISM);
    setRuleMechanism(ruleMechanism);
  }

  public static void main(String[] args) throws Exception {
    setConfiguration(new Configuration());
    for(String arg: args) {

View on GitHub (pinned to 2add963021)

Solutions

1. Verify krb5.conf exists and [libdefaults] default_realm = YOUR.REALM is set; test with kinit and klist
2. Pass -Djava.security.krb5.conf=/path/krb5.conf (or KRB5_CONFIG env) to the JVM if the file is non-standard
3. If you did not intend Kerberos, set hadoop.security.authentication=simple (and remove _ssl variant) in core-site.xml
4. For embedded tests, provide a minimal krb5.conf with a default_realm before UGI.setConfiguration runs

Example fix

# before: no default realm
[libdefaults]
  udp_preference_limit = 1

# after
[libdefaults]
  default_realm = EXAMPLE.COM
  udp_preference_limit = 1

# and launch the JVM with
-Djava.security.krb5.conf=/etc/krb5.conf

if (SecurityUtil.getAuthenticationMethod(conf).equals(
        UserGroupInformation.AuthenticationMethod.KERBEROS)) {
  try {
    KerberosUtil.getDefaultRealm();
  } catch (Exception ke) {
    throw new IllegalStateException(
        "Kerberos enabled but no default realm: check krb5.conf / "
        + System.getProperty("java.security.krb5.conf", "default"), ke);
  }
}
UserGroupInformation.setConfiguration(conf); // now safe

try {
  HadoopKerberosName.setConfiguration(conf);
} catch (IllegalArgumentException e) {
  // Kerberos env broken: fix krb5.conf/default_realm before retrying;
  // do NOT catch-and-continue: auth is unusable
  throw e;
}

When it happens

Trigger: setConfiguration(conf) with authentication method KERBEROS/KERBEROS_SSL while java.security.krb5.conf points to a missing file, krb5.conf lacks a default_realm, or the realm lookup API throws (e.g. KrbException 'Cannot locate default realm'). Note the CATCH is broad (catch Exception): even unexpected runtime errors from the Kerberos config parser land here.

Common situations: Containers/mini-clusters without /etc/krb5.conf; JDK differences (some JDKs need -Djava.security.krb5.conf explicitly); krb5.conf with [libdefaults] missing default_realm; DNS/hostname realm derivation failing; running tests with security enabled but no KDC fixtures.

Related errors

• Server asks us to fall back to SIMPLE auth, but this client
• Missing keyfile property ('%s') for authentication type '%s'
• Unknown authentication type: %s
• AuthenticationMethod.TOKEN + " authentication requires a sec
• Problem with Kerberos auth_to_local name configuration

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