{"record":{"id":"5b6b6ac80c65c0bf","repo":"apache/hadoop","slug":"can-t-get-kerberos-realm","errorCode":null,"errorMessage":"Can't get Kerberos realm","messagePattern":"Can't get Kerberos realm","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/HadoopKerberosName.java","lineNumber":71,"sourceCode":"  /**\n   * Set the static configuration to get and evaluate the rules.\n   * <p>\n   * IMPORTANT: This method does a NOP if the rules have been set already.\n   * If there is a need to reset the rules, the {@link KerberosName#setRules(String)}\n   * method should be invoked directly.\n   * \n   * @param conf the new configuration\n   * @throws IOException raised on errors performing I/O.\n   */\n  public static void setConfiguration(Configuration conf) throws IOException {\n    final String defaultRule;\n    switch (SecurityUtil.getAuthenticationMethod(conf)) {\n      case KERBEROS:\n      case KERBEROS_SSL:\n        try {\n          KerberosUtil.getDefaultRealm();\n        } catch (Exception ke) {\n          throw new IllegalArgumentException(\"Can't get Kerberos realm\", ke);\n        }\n        defaultRule = \"DEFAULT\";\n        break;\n      default:\n        // just extract the simple user name\n        defaultRule = \"RULE:[1:$1] RULE:[2:$1]\";\n        break; \n    }\n    String ruleString = conf.get(HADOOP_SECURITY_AUTH_TO_LOCAL, defaultRule);\n    setRules(ruleString);\n\n    String ruleMechanism = conf.get(HADOOP_SECURITY_AUTH_TO_LOCAL_MECHANISM,  DEFAULT_MECHANISM);\n    setRuleMechanism(ruleMechanism);\n  }\n\n  public static void main(String[] args) throws Exception {\n    setConfiguration(new Configuration());\n    for(String arg: args) {","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/HadoopKerberosName.java#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify krb5.conf exists and [libdefaults] default_realm = YOUR.REALM is set; test with kinit and klist","Pass -Djava.security.krb5.conf=/path/krb5.conf (or KRB5_CONFIG env) to the JVM if the file is non-standard","If you did not intend Kerberos, set hadoop.security.authentication=simple (and remove _ssl variant) in core-site.xml","For embedded tests, provide a minimal krb5.conf with a default_realm before UGI.setConfiguration runs"],"exampleFix":"# before: no default realm\n[libdefaults]\n  udp_preference_limit = 1\n\n# after\n[libdefaults]\n  default_realm = EXAMPLE.COM\n  udp_preference_limit = 1\n\n# and launch the JVM with\n-Djava.security.krb5.conf=/etc/krb5.conf","handlingStrategy":"validation","validationCode":"if (SecurityUtil.getAuthenticationMethod(conf).equals(\n        UserGroupInformation.AuthenticationMethod.KERBEROS)) {\n  try {\n    KerberosUtil.getDefaultRealm();\n  } catch (Exception ke) {\n    throw new IllegalStateException(\n        \"Kerberos enabled but no default realm: check krb5.conf / \"\n        + System.getProperty(\"java.security.krb5.conf\", \"default\"), ke);\n  }\n}\nUserGroupInformation.setConfiguration(conf); // now safe","typeGuard":null,"tryCatchPattern":"try {\n  HadoopKerberosName.setConfiguration(conf);\n} catch (IllegalArgumentException e) {\n  // Kerberos env broken: fix krb5.conf/default_realm before retrying;\n  // do NOT catch-and-continue: auth is unusable\n  throw e;\n}","preventionTips":["Always set -Djava.security.krb5.conf explicitly for daemons; don't rely on platform defaults in containers","Ensure [libdefaults] default_realm exists and kinit succeeds on the host before enabling kerberos","Add a preflight check (KerberosUtil.getDefaultRealm()) at service startup with a clear error message"],"tags":["kerberos","authentication","krb5-conf","configuration","hadoop"],"backgroundTag":"kerberos-default-realm-missing","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}