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.

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…
• Access denied: dfs.http.policy is HTTPS_ONLY.
• AuthenticationMethod.TOKEN + " authentication requires a…
• Failed to obtain current username
• Invalid attribute value for…

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

Appendix: 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)