apache/hadoop · error · IllegalArgumentException

Invalid rule: ${remaining}

Error message

Invalid rule: ${remaining}

What it means

KerberosName.parseRules() compiles the hadoop.security.auth_to_local rule list. Each rule must match the 'RULE:[n:format](regex)replacement[/L]' syntax; if a chunk of the rules string cannot be consumed by the rule parser, the leftover text is thrown back inside IllegalArgumentException('Invalid rule: ...'), naming exactly where parsing stopped.

Source

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

              && nonSimplePattern.matcher(result).find()
              && ruleMechanism.equalsIgnoreCase(MECHANISM_HADOOP)) {
        throw new NoMatchingRule("Non-simple name " + result +
                                 " after auth_to_local rule " + this);
      }
      if (toLowerCase && result != null) {
        result = result.toLowerCase(Locale.ENGLISH);
      }
      return result;
    }
  }

  static List<Rule> parseRules(String rules) {
    List<Rule> result = new ArrayList<Rule>();
    String remaining = rules.trim();
    while (remaining.length() > 0) {
      Matcher matcher = ruleParser.matcher(remaining);
      if (!matcher.lookingAt()) {
        throw new IllegalArgumentException("Invalid rule: " + remaining);
      }
      if (matcher.group(2) != null) {
        result.add(new Rule());
      } else {
        result.add(new Rule(Integer.parseInt(matcher.group(4)),
                            matcher.group(5),
                            matcher.group(7),
                            matcher.group(9),
                            matcher.group(10),
                            "g".equals(matcher.group(11)),
                            "L".equals(matcher.group(12))));
      }
      remaining = remaining.substring(matcher.end());
    }
    return result;
  }

  @SuppressWarnings("serial")

View on GitHub (pinned to 2add963021)

Solutions

1. Read the text after 'Invalid rule:' in the error — it is the exact position where parsing stopped, then fix that rule in auth_to_local
2. Check every rule against 'RULE:[<n>:<format>](<regex>)<replacement>[/L]' with balanced brackets and parentheses
3. Test the corrected config with 'hadoop org.apache.hadoop.security.HadoopKerberosName user@REALM' before restarting services

Example fix

<!-- before -->
<property><name>hadoop.security.auth_to_local</name>
<value>RULE:[1:$1@$0](*.)L</value></property>

<!-- after -->
<property><name>hadoop.security.auth_to_local</name>
<value>RULE:[1:$1@$0](.*)L</value></property>

// smoke-test rules before deploying config
java.util.List<?> unused = org.apache.hadoop.security.HadoopKerberosName.getRules();
// or run: hadoop org.apache.hadoop.security.HadoopKerberosName 'user@REALM'
// a malformed rule throws IllegalArgumentException('Invalid rule: ...') immediately

try { KerberosName.setRules(rulesString); } catch (IllegalArgumentException e) { /* e.getMessage() pinpoints the failing remainder; fix core-site.xml and redeploy */ }

When it happens

Trigger: Loading core-site.xml where auth_to_local contains a typo: 'RULE:[1:$1@$0](.*)L' with unbalanced parentheses, a missing '[n:format]' section, misspelled 'RULE' prefix, or stray separators so the remainder fails to match.

Common situations: Hand-edited auth_to_local rules in core-site.xml; rules copied from MIT krb5 documentation without adapting to Hadoop's RULE syntax; missing the optional '/L' or adding an invalid suffix.

Related errors

• Invalid rule mechanism: ${ruleMech}
• hadoop.security.dns.nameserver requires hadoop.security.dns.
• Running in secure mode, but config doesn't have a keytab for
• Problem with Kerberos auth_to_local name configuration
• Security is enabled but block access tokens (via dfs.block.a

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