apache/hadoop · error · IllegalArgumentException

Invalid rule mechanism: ${ruleMech}

Error message

Invalid rule mechanism: ${ruleMech}

What it means

KerberosName.setRuleMechanism() accepts only 'hadoop' or 'mit' (case-insensitive) for how auth_to_local rules are evaluated ('hadoop' rejects '@' or '/' in results, 'mit' follows MIT Kerberos semantics). Any other non-null value throws IllegalArgumentException naming the bad value; the property drives hadoop.security.auth_to_local.mechanism.

Source

Thrown at hadoop-common-project/hadoop-auth/src/main/java/org/apache/hadoop/security/authentication/util/KerberosName.java:487

   * Set the rules.
   * @param ruleString the rules string.
   */
  public static void setRules(String ruleString) {
    rules = (ruleString != null) ? parseRules(ruleString) : null;
  }

  /**
   *
   * @param ruleMech the evaluation type: hadoop, mit
   *                 'hadoop' indicates '@' or '/' are not allowed the result
   *                 evaluation. 'MIT' indicates that auth_to_local
   *                 rules follow MIT Kerberos evaluation.
   */
  public static void setRuleMechanism(String ruleMech) {
    if (ruleMech != null
            && (!ruleMech.equalsIgnoreCase(MECHANISM_HADOOP)
            && !ruleMech.equalsIgnoreCase(MECHANISM_MIT))) {
      throw new IllegalArgumentException("Invalid rule mechanism: " + ruleMech);
    }
    ruleMechanism = ruleMech;
  }

  /**
   * Get the rule evaluation mechanism
   * @return the rule evaluation mechanism
   */
  public static String getRuleMechanism() {
    return ruleMechanism;
  }

  static void printRules() throws IOException {
    int i = 0;
    for(Rule r: rules) {
      System.out.println(++i + " " + r);
    }
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Set the mechanism to exactly 'hadoop' or 'mit'
2. Or omit the property entirely to keep the default mechanism
3. Validate the value in deployment tooling before it reaches core-site.xml

Example fix

<!-- before -->
<property><name>hadoop.security.auth_to_local.mechanism</name><value>HADOOP</value></property>

<!-- after -->
<property><name>hadoop.security.auth_to_local.mechanism</name><value>hadoop</value></property>

boolean isValidMechanism(String m) {
  return m == null || "hadoop".equalsIgnoreCase(m) || "mit".equalsIgnoreCase(m);
}

not needed — fix the config value; catching and continuing would silently change auth_to_local semantics

When it happens

Trigger: Setting hadoop.security.auth_to_local.mechanism to values like 'HADOOP_KRB5', 'default', or 'Mit ' (trailing space is trimmed? no — raw string mismatch) via setRuleMechanism or core-site.xml.

Common situations: Copy/paste of a wrong mechanism name from old documentation; expecting an 'auto' mode that does not exist; case-variant spellings other than exact hadoop/mit (those two are case-insensitive, others are invalid).

Related errors

• Invalid rule: ${remaining}
• Problem with Kerberos auth_to_local name configuration
• Server asks us to fall back to SIMPLE auth, but this client
• Can't get Kerberos realm
• hadoop.security.dns.nameserver requires hadoop.security.dns.

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